Tabs

Bases: Frame

A container widget for grouping TabItem widgets.

Tabs provides a tab bar with optional divider. It manages the layout, orientation, and styling of child TabItems.

Events

<<TabSelect>>: Fired when a tab is selected (bubbled from TabItem).
<<TabClose>>: Fired when a tab's close button is clicked (bubbled from TabItem).
<<TabAdd>>: Fired when the add button is clicked (if enable_adding=True).

Attributes:

Name	Type	Description
`orient`	`str`	The orientation of the tab bar ('horizontal' or 'vertical').
`variant`	`str`	The visual style variant ('pill' or 'bar').

variable `property`

variable: Variable

Get the underlying tk.Variable for tab selection.

signal `property`

signal: 'Signal[Any]'

Get the Signal for tab selection.

value `property` `writable`

value: str

Get or set the selected tab value.

init

__init__(
    master: Master = None,
    orient: Literal[
        "horizontal", "vertical"
    ] = "horizontal",
    variant: Literal["pill", "bar"] = "bar",
    show_divider: bool = None,
    compound: Literal[
        "left", "right", "top", "bottom", "center", "none"
    ] = "left",
    tab_width: Union[None, int, Literal["stretch"]] = None,
    tab_padding: tuple = (12, 8),
    tab_anchor: str = None,
    enable_closing: Union[bool, Literal["hover"]] = False,
    enable_adding: bool = False,
    variable: Variable = None,
    signal: "Signal[Any]" = None,
    accent: str = None,
    **kwargs,
)

Create a Tabs widget.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget. If None, uses the default root window.	`None`
`orient`	`Literal['horizontal', 'vertical']`	Orientation of the tab bar. 'horizontal' places tabs in a row, 'vertical' places tabs in a column. Default is 'horizontal'.	`'horizontal'`
`variant`	`Literal['pill', 'bar']`	Visual style variant ('pill' or 'bar'). Default is 'bar'.	`'bar'`
`show_divider`	`bool`	Whether to show a divider line. If None (default), automatically set to True for 'bar' variant, False for others.	`None`
`compound`	`Literal['left', 'right', 'top', 'bottom', 'center', 'none']`	How to position icon relative to text in tabs. Passed to all TabItems. Default is 'left'.	`'left'`
`tab_width`	`Union[None, int, Literal['stretch']]`	Width of tabs. None for auto-sizing, an integer for fixed character width, or 'stretch' to expand tabs to fill available space (horizontal only). Default is None.	`None`
`tab_padding`	`tuple`	Padding for all tabs as (horizontal, vertical). Default is (12, 8).	`(12, 8)`
`tab_anchor`	`str`	Anchor for tab text/icon alignment. If None, defaults to 'w' for vertical orientation, 'center' for horizontal.	`None`
`enable_closing`	`Union[bool, Literal['hover']]`	Default close button visibility for all tabs. True=always visible, False=hidden, 'hover'=visible on hover. Can be overridden per-tab via `closable` in add_tab().	`False`
`enable_adding`	`bool`	If True, shows an "add" button. In horizontal orientation, shows a plus icon on the right. In vertical orientation, shows "New Tab" at the bottom. Fires `<<TabAdd>>` event when clicked.	`False`
`variable`	`Variable`	Tk variable for tracking selected tab value.	`None`
`signal`	`'Signal[Any]'`	Reactive Signal for tracking selected tab value.	`None`
`accent`	`str`	Accent token for styling tabs.	`None`
`**kwargs`		Additional arguments passed to Frame.	`{}`

on_tab_added

on_tab_added(callback: Callable) -> str

Bind to <<TabAdd>> event.

Parameters:

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

Returns:

Type	Description
`str`	Binding identifier for use with off_tab_added().

off_tab_added

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

Unbind from <> event.

add

add(
    text: str = "",
    *,
    key: str = None,
    icon: str | dict = None,
    value: Any = None,
    closable: Union[bool, Literal["hover"]] = None,
    close_command: Callable = None,
    command: Callable = None,
    **kwargs,
) -> TabItem

Add a new tab to the tab bar.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to display on the tab.	`''`
`key`	`str`	Unique identifier for the tab. Auto-generated if not provided.	`None`
`icon`	`str \| dict`	Icon to display on the tab.	`None`
`value`	`Any`	Value associated with this tab for selection tracking. If None, defaults to the key.	`None`
`closable`	`Union[bool, Literal['hover']]`	Close button visibility (True, False, or 'hover'). If None, uses the widget's `enable_closing` setting.	`None`
`close_command`	`Callable`	Callback when close button is clicked.	`None`
`command`	`Callable`	Callback when tab is selected.	`None`
`**kwargs`		Additional arguments passed to TabItem.	`{}`

Returns:

Type	Description
`TabItem`	The created TabItem widget.

Raises:

Type	Description
`ValueError`	If a tab with the same key already exists.

remove

remove(key: str) -> None

Remove a tab by its key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key of the tab to remove.	required

Raises:

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

item

item(key: str) -> TabItem

Get a tab by its key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key of the tab to retrieve.	required

Returns:

Type	Description
`TabItem`	The TabItem instance.

Raises:

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

items

items() -> tuple[TabItem, ...]

Get all tab widgets in order.

Returns:

Type	Description
`tuple[TabItem, ...]`	A tuple of all TabItem instances in the order they were added.

keys

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

Get all tab keys in order.

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all tab keys in the order they were added.

configure_item

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

Configure a specific tab by its key.

Parameters:

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

Returns:

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

get

get() -> str

Return the currently selected tab value.

set

set(value: str) -> None

Set the selected tab value.

on_tab_changed

on_tab_changed(callback: Callable) -> Any

Subscribe to tab selection changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable`	Function called with the new selected value.	required

Returns:

Type	Description
`Any`	Subscription ID for use with off_tab_changed().

off_tab_changed

off_tab_changed(bind_id: Any) -> None

Unsubscribe from tab selection changes.

Tabs

variable property

signal property

value property writable

__init__

on_tab_added

off_tab_added

add

remove

item

items

keys

configure_item

get

set

on_tab_changed

off_tab_changed

variable `property`

signal `property`

value `property` `writable`

init