Skip to content

ToggleGroup

Bases: Frame

A group of toggle buttons with single or multi-selection support.

The ToggleGroup widget provides a convenient way to create groups of toggle buttons with automatic position tracking and styling. It supports both single selection (radio button behavior) and multi-selection (checkbox behavior).

variable property writable 

variable: 'tk.Variable'

Get the underlying tk.Variable.

signal property writable 

signal: 'Signal[Any]'

Get the signal.

value property writable 

value: str | set[str]

Get or set the value (string for single mode, set for multi mode).

__init__ 

__init__(
    master: Any = None, **kwargs: Unpack[ToggleGroupKwargs]
)

Initialize the ToggleGroup.

Parameters:

Name Type Description Default
master Any

Parent widget. If None, uses the default root window.

 None

Other Parameters:

Name Type Description
mode str

Selection mode - 'single' for radio button behavior (default), or 'multi' for checkbox behavior allowing multiple selections.
orient str

Layout orientation - 'horizontal' (default) or 'vertical'.
accent str

Accent token for styling (e.g., 'primary', 'danger'). Defaults to 'primary'.
variant str

Style variant (e.g., 'outline', 'ghost').
bootstyle str

DEPRECATED - Use accent and variant instead.
variable Variable

Optional tk.Variable for controlling the value. For single mode, use StringVar; for multi mode, use SetVar.
signal Signal

Optional Signal instance for reactive programming.
value str | set

Initial value - string for single mode, set for multi mode.
show_border bool

If True, draws a border around the group.
surface str

Optional surface token; otherwise inherited.
style_options dict

Additional style options passed to child buttons.
padding int | tuple

Frame padding. Defaults to 1.
width int

Requested width in pixels.
height int

Requested height in pixels.

add 

add(
    text: str = None,
    value: Any = None,
    key: str | None = None,
    **kwargs: Any,
) -> RadioToggle | CheckToggle

Add a toggle button to the group.

Parameters:

Name Type Description Default
text str

Text to display on the button.

 None
value Any

Value this button represents (required).

 None
key str | None

Unique identifier. Defaults to value.

 None
**kwargs Any

Additional arguments passed to RadioToggle or CheckToggle.

 {}

Returns:

Type Description
RadioToggle | CheckToggle

The created button widget.

get 

get() -> str | set[str]

Return the current value (string for single mode, set for multi mode).

set 

set(value: str | set[str]) -> None

Set the value (string for single mode, set for multi mode).

Parameters:

Name Type Description Default
value str | set[str]

The value to set.

 required

Raises:

Type Description
TypeError

If value type doesn't match the mode.

remove 

remove(key: str)

Remove a button by its key.

items 

items() -> tuple[RadioToggle | CheckToggle, ...]

Get all button widgets in the group.

Returns:

Type Description
tuple[RadioToggle | CheckToggle, ...]

A tuple of all button instances in the group.

item 

item(key: str) -> RadioToggle | CheckToggle

Get a button by its key.

Parameters:

Name Type Description Default
key str

The key of the button to retrieve.

 required

Returns:

Type Description
RadioToggle | CheckToggle

The button instance.

Raises:

Type Description
KeyError

If no button with the given key exists.

configure_item 

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

Configure a specific button by its key.

Parameters:

Name Type Description Default
key str

The key of the button to configure.

 required
option str

If provided, return the value of this option.

 None
**kwargs Any

Configuration options to apply to the button.

 {}

Returns:

Type Description

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

keys 

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

Get all button keys.

Returns:

Type Description
tuple[str, ...]

A tuple of all button keys in the group.

on_changed 

on_changed(callback: Callable) -> Any

Subscribe to value changes. Callback receives new_value: str | set[str] directly (str in 'single' mode, set in 'multi' mode).

off_changed 

off_changed(bind_id: Any) -> None

Unsubscribe from value changes.