Toggle Button

A toggle button allows users to toggle a selection on or off, providing a way to switch between two states, such as enabling or disabling a feature.

Example

UI Recommendations

If you want to represent a binary choice for the user, consider using a checkbox.

Content

A toggle button accepts a label, an icon, or both as children.

Accessibility

If no text is passed into the toggle button, and hence, it has no visible label, the aria_label prop should be set for accessibility.

Value

A toggle button is not selected by default. Use the default_selected prop to set the initial state (uncontrolled) or the is_selected prop to control the selected state.

Events

The on_change property is triggered whenever the value in the toggle button group selection is changed.

Quiet state

The is_quiet prop makes a toggle button “quiet”. This can be useful when the toggle button and its corresponding styling should not distract users from surrounding content.

Disabled state

The is_disabled prop disables a toggle button to prevent user interaction. This is useful when the toggle button should be visible but not available for selection.

Emphasized

The is_emphasized prop makes the toggle button the user’s accent color when selected, adding a visual prominence to the selection.

Static Color

The static_color prop can be used when the toggle button is placed over a colored background.

API Reference

ToggleButtons allow users to toggle a selection on or off, for example switching between two states or modes.

Returns: Element The rendered toggle button element.

Parameters	Type	Default	Description
*children	Any		The children to render inside the button.
is_emphasized	bool | None	None	Whether the button should be displayed with an emphasized style.
is_selected	bool | None	None	Whether the button is selected.
default_selected	bool | None	None	Whether the button is selected by default.
is_disabled	bool | None	None	Whether the button is disabled.
auto_focus	bool | None	None	Whether the button should automatically get focus when the page loads.
is_quiet	bool | None	None	Whether the button should be quiet.
static_color	Literal['white', 'black'] | None	None	The static color style to apply. Useful when the button appears over a color background.
type	Literal['button', 'submit', 'reset']	'button'	The type of button to render. (default: "button")
key	str | None	None	A unique identifier used by React to render elements in a list.