ButtonGroup

Bases: Frame

A group of buttons with automatic positioning and styling.

ButtonGroup provides visual grouping of buttons (or other widgets) without state tracking. Perfect for toolbars, action button groups, or any scenario where you want buttons visually connected but don't need to track which is selected.

init

__init__(
    master: Master = None,
    *,
    orient: Literal[
        "horizontal", "vertical"
    ] = "horizontal",
    accent: str = None,
    variant: str = "solid",
    density: Literal["default", "compact"] = "default",
    state: Literal["normal", "disabled"] = "normal",
    **kwargs: Unpack[ButtonGroupKwargs],
)

Initialize the ButtonGroup.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget. If None, uses the default root window.	`None`

Other Parameters:

Name	Type	Description
`orient`	`str`	Layout orientation - 'horizontal' (default) or 'vertical'.
`accent`	`str`	The accent token (e.g., 'primary', 'success', 'danger').
`variant`	`str`	The style variant (e.g., 'solid', 'outline', 'ghost'). Defaults to 'solid',
`state`	`str`	Initial state for all buttons - 'normal' (default) or 'disabled'.
`surface`	`str`	Optional surface token; otherwise inherited.
`density`	`str`	The vertical and horizontal compactness of widget content, e.g. 'default', 'compact'.
`padding`	`int \| tuple`	Frame padding. Defaults to 1.
`width`	`int`	Requested width in pixels.
`height`	`int`	Requested height in pixels.
`style_options`	`dict`	Additional style options passed to child widgets.

add

add(
    text: str = None,
    *,
    key: str = None,
    widget_type: type = None,
    command: Callable[[], Any] = None,
    **kwargs: Any,
) -> "tk.Widget"

Add a widget to the group.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to display on the widget.	`None`
`key`	`str`	Unique identifier. Auto-generated if not provided.	`None`
`widget_type`	`type`	Widget class to instantiate (defaults to Button).	`None`
`command`	`Callable[[], Any]`	Callback for button press.	`None`
`**kwargs`	`Any`	Additional arguments passed to the widget constructor.	`{}`

Returns:

Type	Description
`'tk.Widget'`	The created widget instance.

Raises:

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

remove

remove(key: str)

Remove a widget by its key.

Parameters:

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

Raises:

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

item

item(key: str) -> 'tk.Widget'

Get a widget by its key.

Parameters:

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

Returns:

Type	Description
`'tk.Widget'`	The widget instance.

Raises:

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

configure_item

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

Configure a specific widget by its key.

Parameters:

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

Returns:

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

Examples:

group.configure_item("save_btn", state='disabled') current_state = group.configure_item("save_btn", 'state')

items

items() -> tuple['tk.Widget', ...]

Get all widgets in the group.

Returns:

Type	Description
`tuple['tk.Widget', ...]`	A tuple of all widget instances in the group.

keys

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

Get all widget keys.

Returns:

Type	Description
`tuple[str, ...]`	A tuple of all widget keys in the group.

len

__len__() -> int

Return the number of widgets in the group.

Examples:

>>> count = len(button_group)

contains

__contains__(key: str) -> bool

Check if a widget with the given key exists in the group.

Examples:

>>> if 'save' in button_group:
...     print('Save button exists')

iter

__iter__()

Iterate over the widgets in the group.

Examples:

>>> for widget in button_group:
...     widget.configure(state='disabled')