ToggleButton
Toggle a persistent state with independently configured off and on button variants.
Anatomy#
Usage#
Use ToggleButton for persistent on/off actions such as bold formatting or bookmarking. It renders a
native button and exposes its state through aria-pressed. Use Button for a
one-shot command. Join several toggles with ButtonGroup for layout only;
the group does not coordinate selection.
Off and on variants#
variant sets the unpressed appearance and activeVariant sets the pressed appearance. Both
accept all Button variants, and the defaults are ghost and soft. tone and activeTone pick
the color the same way (both default to neutral). Changing a variant does not reset the pressed
state. The link variant only changes appearance; ToggleButton still renders a button that
toggles, not a link.
Controlled and uncontrolled state#
Use defaultPressed to initialize an uncontrolled button. Pass pressed and onPressedChange when
application state owns the value. Controlled activation reports the requested next value and waits
for the caller to update pressed. onPressedChange does not fire for programmatic changes to
pressed.
Your onClick runs before the toggle. Calling event.preventDefault() cancels both the state
change and onPressedChange.
Icons and accessible names#
Keep the accessible name stable while toggling. Use aria-label for icon-only buttons;
aria-pressed then reports the on or off state. Disabled and loading buttons suppress activation.
Children can be a render function that receives reactive pressed and loading values. Use it to
style the content from the pressed state without remounting the button’s children. Declare the
function’s parameter even when you do not use it; a zero-argument function is called as an
accessor and is not mounted as a component.
Async actions#
autoLoading follows a Promise returned by onClick and blocks repeated activation until it
settles. The state changes immediately after an uncancelled click, including when the Promise later
rejects; it is not automatically rolled back. Handle request errors in your async handler. To update
only after success, use controlled pressed and update it after the request completes.
Theme and groups#
Configure toggleButton.defaultVariants to choose the default off and on appearances and size.
Button’s theme still supplies the underlying variant styles; toggleButton.base, classes, and
styles add component-specific presentation. Instance styling follows the standard root and slot
override rules.
Inside ButtonGroup, ToggleButton inherits the group’s size and variant. The group’s tone sets both
the unpressed tone and the pressed activeTone. Its pressed variant comes from its own
configuration. Any prop set on the ToggleButton overrides the inherited value.
The root uses data-slot="toggle-button" and exposes data-pressed while pressed. The leading,
label, and trailing elements retain the corresponding button-* data-slot names.
Examples#
Pin a conversation#
Own pressed when another control on the page must reset the same flag.
Toggle formatting and a bookmark#
Keep aria-label stable on icon-only toggles. Use a child render function when the glyph itself
should change with pressed.
Turn on notifications in a toolbar#
Theme defaults can set size and variants for a page region. ButtonGroup only joins the formatting toggles visually.
API Reference#
Attributes#
data-pressedProps#
Renders a <button> element by default.