Toggle
A two-state button. Turn a setting on or off. Keep the state visible.
NewInstallation
Copy and paste the following code into your project.
Update the import paths to match your project structure.
Anatomy
Composition
Toggle is a single part: a button with aria-pressed. To group several of them, use Toggle Group, and inside a Toolbar use Toolbar.Toggle.A pressed toggle uses the muted fill, never the primary color. It shows a state, it is not the main action on the page.
Variants
Default
Outline with text
Add a label next to the icon when the state needs words. With text inside, you can drop
aria-label.Keyboard
| Key | Action |
|---|---|
Tab | Moves focus to the toggle |
Space, Enter | Turns the toggle on or off |
Accessibility
- Renders a native
button type="button"witharia-pressed, so screen readers announce it as a toggle button and read whether it is pressed. - Give an icon-only toggle an
aria-labelthat names the setting, like "Bold", not the action. The pressed state already says whether it is on. data-state="on"ordata-state="off"is there for styling, alongsidedata-disabledwhen it is disabled.
API Reference
Toggle
Accepts every
button attribute as well.| Prop | Type | Default | Description |
|---|---|---|---|
pressed | boolean | - | Controlled pressed state |
defaultPressed | boolean | false | Initial pressed state when uncontrolled |
onPressedChange | (pressed: boolean) => void | - | Called when the pressed state changes |
variant | 'default' | 'outline' | 'default' | Transparent, or with an input border |
size | 'sm' | 'default' | 'lg' | 'default' | Height of 32, 36 or 40px. Icon-only is square |
disabled | boolean | false | Blocks interaction |
className | string | - | Additional CSS classes |
The file also exports
toggleVariants, the class recipe that Toggle Group reuses for its items.Found something to improve?
Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.