Skip to content

SideNavGroup

Bases: Frame

A collapsible group of navigation items.

SideNavGroup provides a container for related navigation items. In expanded mode, it behaves like an Expander with a chevron toggle. In compact mode, clicking the group shows a popup flyout to the right containing the group's items.

Uses a single CompositeFrame container with separate icon, text, and chevron labels. In compact mode, text and chevron are hidden and the icon is centered.

The group shows as selected if any of its child items are currently selected.

Events

  • <<GroupExpanding>>: Fired before the group expands. event.data = {'key': str}
  • <<GroupCollapsed>>: Fired after the group collapses. event.data = {'key': str}
Example 
# Groups are created via SideNav.add_group()
nav.add_group('files', text='Files', icon='folder')
nav.add_item('local', text='Local', icon='hdd', group='files')
nav.add_item('cloud', text='Cloud', icon='cloud', group='files')

key property 

key: str

Get the group's unique key.

content_frame property 

content_frame: Frame

Get the content frame for adding items.

is_expanded property 

is_expanded: bool

Check if group is currently expanded.

has_items property 

has_items: bool

Check if this group has any items.

items property 

items: list['SideNavItem']

Get all items in order.

is_any_selected property 

is_any_selected: bool

Check if any child item is selected.

__init__ 

__init__(
    master: Master = None,
    key: str = "",
    text: str = "",
    icon: str | dict = None,
    signal: "Signal[Any]" = None,
    variable: Variable = None,
    is_expanded: bool = False,
    **kwargs: Unpack[SideNavGroupKwargs],
)

Initialize a SideNavGroup.

Parameters:

Name Type Description Default
master Master | None

Parent widget.

 None
key str

Unique identifier for this group.

 ''
text str

Display text for the group.

 ''
icon str | dict | None

Icon name or configuration dict.

 None
signal Signal | None

Reactive signal for selection state.

 None
variable Variable | None

Shared variable for selection tracking.

 None
is_expanded bool

Initial expansion state. Default False.

 False
**kwargs Unpack[SideNavGroupKwargs]

Additional arguments passed to Frame.

 {}

set_child_selected 

set_child_selected(has_selected_child: bool) -> None

Directly set whether a child is selected.

This is called by SideNav for efficient selection updates, avoiding the need to iterate through children.

Parameters:

Name Type Description Default
has_selected_child bool

True if any child item is selected.

 required

set_compact 

set_compact(compact: bool) -> None

Set compact mode.

In compact mode, only the icon is shown and clicking opens a popup with the group's items.

Parameters:

Name Type Description Default
compact bool

True for compact mode, False for full display.

 required

expand 

expand() -> None

Expand to show items (expanded mode only).

collapse 

collapse() -> None

Collapse to hide items (expanded mode only).

toggle 

toggle() -> None

Toggle expansion state (expanded mode only).

destroy 

destroy()

Clean up resources.