Toggle
Two-state button for toggling between on and off
A toggle is a two-state button that stays pressed when on. Use it for a single on/off control like bold, mute, or pin. For a set of mutually exclusive or multi-select toggles, use Toggle Group; for a labeled settings switch, use Switch.
Preview
Installation
Usage
Examples
Sizes
Use size to set the toggle's height and padding.
| Size | Description |
|---|---|
sm | Compact, for dense toolbars. |
default | The standard height. |
lg | Taller, for prominent controls. |
With Text
Place a text label alongside the icon inside the toggle.
Solid Variant
Set variant="solid" for a filled button: a muted plate when off that insets when on (the same treatment the detached toggle group gives its cells).
Outline Variant
Set variant="outline" to frame the toggle with a border.
| Variant | Description |
|---|---|
ghost | Borderless. Transparent when off, filled when on. Default. |
solid | Muted plate when off; insets to the selected overlay when on. |
outline | Framed with a border. Fills when on. |
Controlled
Use pressed and onPressedChange to drive the toggle state yourself.
Disabled State
Use disabled to prevent interaction.
Accessibility
Label icon-only toggles
An icon-only toggle has no text for a screen reader to announce. Give it an aria-label describing the action it controls.
API Reference
The Toggle component is built on top of Base UI's Toggle. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.
For the complete Base UI API, see the Base UI Toggle documentation.