Skip to content

SideNavItem

Bases: Frame

A selectable navigation item with icon and text.

SideNavItem uses a CompositeFrame container with separate icon and text label children. This provides synchronized hover/pressed/selected states across all elements and precise control over layout.

The widget supports expanded and compact modes. In compact mode, only the icon is displayed and it remains perfectly centered due to symmetrical padding. In expanded mode, both icon and text are visible.

Uses NavigationButton.TFrame for the container (with selection indicator) and NavigationButton.TLabel for the icon and text labels.

Events

  • <<ItemInvoked>>: Fired when the item is clicked. event.data = {'key': str}
Example 
# Items are typically created via SideNav.add_item()
nav.add_item('home', text='Home', icon='house')
nav.add_item('local', text='Local', icon='hdd', group='files')

key property 

key: str

Get the item's unique key.

is_selected property 

is_selected: bool

Check if this item is currently selected.

is_enabled property 

is_enabled: bool

Check if this item is enabled.

signal property 

signal: 'Signal[Any] | None'

Get the signal for selection state.

variable property 

variable: Variable | None

Get the variable for selection state.

__init__ 

__init__(
    master: Master = None,
    key: str = "",
    text: str = "",
    icon: str | dict = None,
    signal: "Signal[Any]" = None,
    variable: Variable = None,
    is_enabled: bool = True,
    indent_level: int = 0,
    command: Callable = None,
    padding_x: int = None,
    padding_y: int = None,
    icon_gap: int = None,
    **kwargs: Unpack[SideNavItemKwargs],
)

Initialize a SideNavItem.

Parameters:

Name Type Description Default
master Master | None

Parent widget.

 None
key str

Unique identifier for this item (used as selection value).

 ''
text str

Display text for the item.

 ''
icon str | dict | None

Icon name or configuration dict.

 None
signal Signal | None

Reactive signal for selection state (preferred).

 None
variable Variable | None

Shared variable for radio group selection.

 None
is_enabled bool

Whether the item is interactive. Default True.

 True
indent_level int

Nesting level for indentation (0 = root, 1 = child). Default 0.

 0
command Callable | None

Callback invoked when item is clicked.

 None
padding_x int | None

Horizontal padding on edges. Default is 12.

 None
padding_y int | None

Vertical padding. Default is 8.

 None
icon_gap int | None

Gap between icon and text. Default is 8.

 None
**kwargs Unpack[SideNavItemKwargs]

Additional arguments passed to Frame.

 {}

set_selected 

set_selected(selected: bool) -> None

Directly set the selection visual state.

This is called by SideNav for efficient selection updates, avoiding the need to query the variable.

Parameters:

Name Type Description Default
selected bool

True to show as selected, False otherwise.

 required

select 

select() -> None

Select this item (set the variable to this item's key).

set_enabled 

set_enabled(enabled: bool) -> None

Set the enabled state.

Parameters:

Name Type Description Default
enabled bool

True to enable, False to disable.

 required

set_compact 

set_compact(compact: bool) -> None

Set compact mode (icon only, no text).

Parameters:

Name Type Description Default
compact bool

True for compact mode, False for full display.

 required

on_invoked 

on_invoked(callback) -> str

Bind to <<ItemInvoked>>.

Parameters:

Name Type Description Default
callback

Function to call when item is invoked.

 required

Returns:

Name Type Description
str str

Binding identifier for use with off_invoked().

off_invoked 

off_invoked(bind_id: str = None) -> None

Unbind from <<ItemInvoked>>.

Parameters:

Name Type Description Default
bind_id str | None

Binding identifier from on_invoked().

 None