Skip to content

RadioGroup

Bases: Frame

A group of radio buttons with automatic state tracking and optional label.

The RadioGroup widget provides a convenient way to create groups of radio buttons with automatic state management. It supports both horizontal and vertical orientations, and can display an optional label in various positions.

Attributes:

Name Type Description
variable Variable

The underlying tk.Variable for the selected value.
signal Signal

Signal for reactive programming and change subscriptions.

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

Get or set the selected value.

__init__ 

__init__(
    master: Master = None,
    **kwargs: Unpack[RadioGroupKwargs],
)

Initialize the RadioGroup.

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

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

DEPRECATED - Use accent instead.
text str

Optional label text to display.
labelanchor str

Label position - 'n' (top, default), 's' (bottom), 'e' (right), 'w' (left), or combinations like 'nw', 'ne', etc.
variable Variable

Optional tk.StringVar for controlling the selected value.
signal Signal

Optional Signal instance for reactive programming.
value str

Initial selected value.
state str

Initial state for all buttons - 'normal' (default) or 'disabled'.
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,
) -> RadioButton

Add a radio 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 RadioButton.

 {}

Returns:

Type Description
RadioButton

The created RadioButton widget.

Raises:

Type Description
ValueError

If value is None or if a button with the same key already exists.

get 

get() -> str

Return the currently selected value.

set 

set(value: str) -> None

Set the selected value.

Parameters:

Name Type Description Default
value str

The value to select (must match a button's value).

 required

Raises:

Type Description
TypeError

If value is not a string.
ValueError

If value doesn't exist in the group.

remove 

remove(key: str)

Remove a button by its key.

Parameters:

Name Type Description Default
key str

The key of the button to remove.

 required

Raises:

Type Description
KeyError

If no button with the given key exists.

items 

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

Get all button widgets in the group.

Returns:

Type Description
tuple[RadioButton, ...]

A tuple of all RadioButton instances in the group.

item 

item(key: str) -> RadioButton

Get a button by its key.

Parameters:

Name Type Description Default
key str

The key of the button to retrieve.

 required

Returns:

Type Description
RadioButton

The RadioButton 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.

on_changed 

on_changed(callback: Callable) -> Any

Subscribe to value changes. Callback receives new_value: str directly.

off_changed 

off_changed(bind_id: Any) -> None

Unsubscribe from value changes.

keys 

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

Get all button keys.

Returns:

Type Description
tuple[str, ...]

A tuple of all button keys in the group.

values 

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

Get all possible values.

Returns:

Type Description
tuple[str, ...]

A tuple of all values that can be selected.

__len__ 

__len__() -> int

Return the number of buttons in the group.

__contains__ 

__contains__(key: str) -> bool

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