Skip to content

Expander

Bases: Frame

A collapsible container with a clickable header and expandable content.

The Expander displays a header with an optional icon, title, and chevron button. Clicking anywhere on the header toggles the visibility of the content area.

Expander also supports selection state via signal/variable and value, similar to RadioButton. When clicked, it sets the variable to its value, enabling radio-group-like behavior for navigation.

Attributes:

Name Type Description
content Frame

The content container frame (read-only).
is_selected bool

Whether this expander's value matches the variable (read-only).

Events

  • <<Toggle>>: Fired when expanded/collapsed. event.data = {'expanded': bool}
  • <<Selected>>: Fired when this expander is selected. event.data = {'value': Any}

content property 

content: Frame

Get the content frame (for direct child parenting).

is_selected property 

is_selected: bool

Check if this expander is currently selected.

__init__ 

__init__(
    master: Master = None,
    title: str = "",
    icon: str | dict = None,
    expanded: bool = True,
    collapsible: bool = True,
    highlight: bool = False,
    icon_expanded: str | dict = None,
    icon_collapsed: str | dict = None,
    icon_position: Literal["before", "after"] = "after",
    signal: "Signal[Any]" = None,
    variable: Variable = None,
    value: Any = None,
    **kwargs,
)

Create an Expander widget.

Parameters:

Name Type Description Default
master Master

Parent widget. If None, uses the default root window.

 None
title str

Header title text.

 ''
icon str | dict

Icon to display in header (left of title).

 None
expanded bool

Initial expansion state. Default is True (expanded).

 True
collapsible bool

Whether the expander can be toggled. Default is True.

 True
highlight bool

If True, header shows 'selected' state when expanded.

 False
icon_expanded str | dict

Icon spec for expanded state. Default is chevron-up.

 None
icon_collapsed str | dict

Icon spec for collapsed state. Default is chevron-down.

 None
icon_position Literal['before', 'after']

Position of chevron relative to title.

 'after'
signal Signal

Reactive Signal for selection state (preferred over variable).

 None
variable Variable

Tk variable for selection state (synced with signal).

 None
value Any

Value to set on signal/variable when selected.

 None
**kwargs

Additional arguments passed to Frame. Use accent and variant for styling the header and chevron.

 {}

toggle 

toggle()

Toggle expanded/collapsed state.

expand 

expand()

Expand the content area.

collapse 

collapse()

Collapse the content area.

select 

select()

Select this expander (set variable to this expander's value).

add 

add(widget: Widget = None, **kwargs) -> Widget

Add content widget, or create and return an empty frame.

Parameters:

Name Type Description Default
widget Widget | None

Optional widget to use as content. If None, creates a Frame.

 None
**kwargs

When widget is None, these are passed to Frame (e.g., padding).

 {}

Returns:

Name Type Description
Widget Widget

The content widget (passed or created).

Raises:

Type Description
ValueError

If content already exists and widget is provided.

on_toggled 

on_toggled(callback: Callable) -> str

Bind callback to <<Toggle>> events.

Parameters:

Name Type Description Default
callback Callable

Function to call when toggled. Receives event with event.data = {'expanded': bool}.

 required

Returns:

Type Description
str

Bind ID that can be passed to off_toggled to remove this callback.

off_toggled 

off_toggled(bind_id: str | None = None) -> None

Unbind <<Toggle>> callback(s).

Parameters:

Name Type Description Default
bind_id str | None

Bind ID returned by on_toggled. If None, unbinds all.

 None

on_selected 

on_selected(callback: Callable) -> str

Bind callback to <<Selected>> events.

Parameters:

Name Type Description Default
callback Callable

Function to call when selected. Receives event with event.data = {'value': Any}.

 required

Returns:

Type Description
str

Bind ID that can be passed to off_selected to remove this callback.

off_selected 

off_selected(bind_id: str = None)

Unbind <<Selected>> callback(s).

Parameters:

Name Type Description Default
bind_id str | None

Bind ID returned by on_selected. If None, unbinds all.

 None