SideNav

Bases: Frame

A sidebar navigation container with header, scrollable items, and footer.

SideNav provides a complete navigation solution with: - Pane header with optional title and menu button - Scrollable navigation items area - Groups for organizing related items (expand/collapse in expanded mode, popup flyout in compact mode) - Footer section for settings and other fixed items - Display modes: expanded (full), compact (icons only), minimal (hidden)

The pane manages a shared selection variable/signal that all items use for radio-group behavior.

Events

<<PaneToggled>>: Fired when pane is opened/closed. event.data = {'is_open': bool}
<<DisplayModeChanged>>: Fired when display mode changes. event.data = {'mode': str}
<<SelectionChanged>>: Fired when selected item changes. event.data = {'key': str}
<<BackRequested>>: Fired when back button is clicked.

Example

nav = SideNav(root, title='My App')

# Add root-level items
nav.add_item('home', text='Home', icon='house')
nav.add_item('docs', text='Documents', icon='file-earmark-text')

# Add a group with items
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')

# Add section header
nav.add_header('Favorites')
nav.add_item('photos', text='Photos', icon='image')

# Add footer item
nav.add_footer_item('settings', text='Settings', icon='gear')

# Bind to selection
nav.on_selection_changed(lambda e: print(f"Selected: {e.data['key']}"))

is_pane_open `property`

is_pane_open: bool

Check if the pane is open.

display_mode `property`

display_mode: DisplayMode

Get the current display mode.

selected_key `property`

selected_key: str | None

Get the currently selected item key.

signal `property`

signal: 'Signal[str] | None'

Get the selection signal.

variable `property`

variable: Variable | None

Get the selection variable.

init

__init__(
    master: Master = None,
    title: str = "",
    show_header: bool = True,
    show_back_button: bool = False,
    collapsible: bool = True,
    display_mode: DisplayMode = "expanded",
    is_pane_open: bool = True,
    pane_width: int = None,
    signal: "Signal[str]" = None,
    variable: Variable = None,
    accent: str = "primary",
    **kwargs: Unpack[SideNavKwargs],
)

Initialize a SideNav.

Parameters:

Name	Type	Description	Default
`master`	`Master \| None`	Parent widget.	`None`
`title`	`str`	Title displayed in the pane header.	`''`
`show_header`	`bool`	Show internal header with toolbar. Default True. Set to False when using an external toolbar.	`True`
`show_back_button`	`bool`	Show back button in header. Default False.	`False`
`collapsible`	`bool`	Allow pane to collapse. Shows hamburger menu. Default True.	`True`
`display_mode`	`DisplayMode`	Initial display mode. Default 'expanded'.	`'expanded'`
`is_pane_open`	`bool`	Initial pane state. Default True.	`True`
`pane_width`	`int \| None`	Custom pane width. Uses default based on mode.	`None`
`signal`	`Signal \| None`	Reactive signal for selection state.	`None`
`variable`	`Variable \| None`	Tk variable for selection state.	`None`
`accent`	`str`	Accent color for selection indicators. Default 'primary'.	`'primary'`
`**kwargs`	`Unpack[SideNavKwargs]`	Additional arguments passed to Frame.	`{}`

add_group

add_group(
    key: str,
    text: str = "",
    icon: str | dict = None,
    is_expanded: bool = False,
    **kwargs,
) -> SideNavGroup

Add a navigation group to the pane.

Groups contain related items and can be expanded/collapsed in expanded mode. In compact mode, clicking a group shows a popup with its items.

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for the group.	required
`text`	`str`	Display text.	`''`
`icon`	`str \| dict \| None`	Icon name or configuration.	`None`
`is_expanded`	`bool`	Initial expansion state. Default False.	`False`
`**kwargs`		Additional arguments passed to SideNavGroup.	`{}`

Returns:

Name	Type	Description
`SideNavGroup`	`SideNavGroup`	The created group.

Raises:

Type	Description
`ValueError`	If a group or item with the given key already exists.

add_item

add_item(
    key: str,
    text: str = "",
    icon: str | dict = None,
    group: str = None,
    **kwargs,
) -> SideNavItem

Add a navigation item to the pane.

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for the item.	required
`text`	`str`	Display text.	`''`
`icon`	`str \| dict \| None`	Icon name or configuration.	`None`
`group`	`str \| None`	Key of the group to add this item to. If None, item is added at root level.	`None`
`**kwargs`		Additional arguments passed to SideNavItem.	`{}`

Returns:

Name	Type	Description
`SideNavItem`	`SideNavItem`	The created item.

Raises:

Type	Description
`ValueError`	If an item with the given key already exists.
`ValueError`	If the specified group does not exist.

add_header

add_header(text: str, **kwargs) -> SideNavHeader

Add a section header to the pane.

Headers are hidden in compact display mode.

Parameters:

Name	Type	Description	Default
`text`	`str`	Header text.	required
`**kwargs`		Additional arguments passed to SideNavHeader.	`{}`

Returns:

Name	Type	Description
`SideNavHeader`	`SideNavHeader`	The created header.

add_separator

add_separator(**kwargs) -> SideNavSeparator

Add a separator to the pane.

Parameters:

Name	Type	Description	Default
`**kwargs`		Additional arguments passed to SideNavSeparator.	`{}`

Returns:

Name	Type	Description
`SideNavSeparator`	`SideNavSeparator`	The created separator.

add_footer_item

add_footer_item(
    key: str,
    text: str = "",
    icon: str | dict = None,
    **kwargs,
) -> SideNavItem

Add a navigation item to the footer section.

Parameters:

Name	Type	Description	Default
`key`	`str`	Unique identifier for the item.	required
`text`	`str`	Display text.	`''`
`icon`	`str \| dict \| None`	Icon name or configuration.	`None`
`**kwargs`		Additional arguments passed to SideNavItem.	`{}`

Returns:

Name	Type	Description
`SideNavItem`	`SideNavItem`	The created item.

Raises:

Type	Description
`ValueError`	If an item with the given key already exists.

node

node(key: str) -> SideNavItem

Get an item by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The item key.	required

Returns:

Name	Type	Description
`SideNavItem`	`SideNavItem`	The item.

Raises:

Type	Description
`KeyError`	If no item with the given key exists.

nodes

nodes() -> tuple[SideNavItem, ...]

Get all items (excluding footer items).

Returns:

Type	Description
`tuple[SideNavItem, ...]`	A tuple of all SideNavItem instances.

node_keys

node_keys() -> tuple[str, ...]

Get all item keys (excluding footer items).

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all item keys.

group

group(key: str) -> SideNavGroup

Get a group by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The group key.	required

Returns:

Name	Type	Description
`SideNavGroup`	`SideNavGroup`	The group.

Raises:

Type	Description
`KeyError`	If no group with the given key exists.

groups

groups() -> tuple[SideNavGroup, ...]

Get all groups.

Returns:

Type	Description
`tuple[SideNavGroup, ...]`	A tuple of all SideNavGroup instances.

configure_node

configure_node(key: str, option: str = None, **kwargs: Any)

Configure a specific item by its key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key of the item to configure.	required
`option`	`str`	If provided, return the value of this option.	`None`
`**kwargs`	`Any`	Configuration options to apply to the item.	`{}`

Returns:

Type	Description
	If option is provided, returns the value of that option.

remove_item

remove_item(key: str) -> None

Remove an item by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The item key to remove.	required

remove_group

remove_group(key: str) -> None

Remove a group and all its items.

Parameters:

Name	Type	Description	Default
`key`	`str`	The group key to remove.	required

select

select(key: str) -> None

Select an item by key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The item key to select.	required

toggle_pane

toggle_pane() -> None

Toggle the pane between expanded and compact modes.

In minimal mode, this toggles visibility instead.

open_pane

open_pane() -> None

Open the pane.

close_pane

close_pane() -> None

Close the pane.

set_display_mode

set_display_mode(mode: DisplayMode) -> None

Set the display mode.

Parameters:

Name	Type	Description	Default
`mode`	`DisplayMode`	'expanded', 'compact', or 'minimal'.	required

footer_nodes

footer_nodes() -> tuple[SideNavItem, ...]

Get all footer items in order.

Returns:

Type	Description
`tuple[SideNavItem, ...]`	A tuple of all footer SideNavItem instances.

footer_node_keys

footer_node_keys() -> tuple[str, ...]

Get all footer item keys in order.

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all footer item keys.

on_selection_changed

on_selection_changed(callback) -> str

Bind to <<SelectionChanged>>.

Parameters:

Name	Type	Description	Default
`callback`		Function to call when selection changes.	required

Returns:

Name	Type	Description
`str`	`str`	Binding identifier.

off_selection_changed

off_selection_changed(bind_id: str = None) -> None

Unbind from <<SelectionChanged>>.

on_back_requested

on_back_requested(callback) -> str

Bind to <<BackRequested>>.

Parameters:

Name	Type	Description	Default
`callback`		Function to call when back button is clicked.	required

Returns:

Name	Type	Description
`str`	`str`	Binding identifier.

off_back_requested

off_back_requested(bind_id: str = None) -> None

Unbind from <<BackRequested>>.

on_pane_toggled

on_pane_toggled(callback) -> str

Bind to <<PaneToggled>>.

Parameters:

Name	Type	Description	Default
`callback`		Function to call when pane is toggled.	required

Returns:

Name	Type	Description
`str`	`str`	Binding identifier.

off_pane_toggled

off_pane_toggled(bind_id: str = None) -> None

Unbind from <<PaneToggled>>.

SideNav

is_pane_open property

display_mode property

selected_key property

signal property

variable property

__init__

add_group

add_item

add_header

add_separator

add_footer_item

node

nodes

node_keys

group

groups

configure_node

remove_item

remove_group

select

toggle_pane

open_pane

close_pane

set_display_mode

footer_nodes

footer_node_keys

on_selection_changed

off_selection_changed

on_back_requested

off_back_requested

on_pane_toggled

off_pane_toggled

is_pane_open `property`

display_mode `property`

selected_key `property`

signal `property`

variable `property`

init