Toggle
A two-state button that stays pressed. Quiet at rest, a tint on hover, a stronger tint with ink text when on. Radix sets aria-pressed. Source: src/components/ui/toggle.tsx.
Icon toggles
The common case: formatting or view options in a toolbar. Each needs an aria-label. Click them; the sample text follows.
The quick brown fox drafts a weekly summary.
With text
Mark a leading icon with data-icon="inline-start" and the padding on that side tightens by 2px. Keep the label the same in both states; the fill says whether it is on.
Variants
Default has no rest edge; outline adds a hairline for a toggle on the bare canvas.
Sizes
Three heights. sm also drops its text to 12.8px and its icon to 14px.
States
On is styled from data-state, aria-pressed or aria-checked, so a Tooltip trigger wrapping it doesn't lose the look. aria-invalid draws a destructive ring.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "outline" | "default" | outline adds the hairline edge (shadow-edge). |
| size | "sm" | "default" | "lg" | "default" | 28, 32 or 36px tall; square at minimum width for a lone icon. |
| pressed | boolean | — | Controlled on state. |
| defaultPressed | boolean | false | Uncontrolled initial state. |
| onPressedChange | (pressed: boolean) => void | — | Fires on click, Space and Enter. |
| disabled | boolean | false | 50% and no pointer events. |
| ...props | ComponentProps<typeof TogglePrimitive.Root> | — | A button. className merges last. Unlike Button it does not mirror data-variant or data-size, and default is 32px where Button's is 36px. |
Best practices
When to use
- A single on/off that belongs in a toolbar: bold, pin, show grid.
- Several related toggles, or one-of-many: a Toggle group.
- A setting in a form or settings page is a Switch; a filter chip that reads as a Button is Button variant="chip".
Behavior
- The pressed state is the feedback; don't also swap the icon for a different glyph.
- Keep the label's weight constant on and off; only fill and colour change.
Accessibility
- Icon-only toggles need aria-label; the label should not change with state (aria-pressed says on or off).
- Pair an icon-only toggle with a Tooltip repeating its label.
- default (32px) and sm (28px) are under 44px; keep them to pointer-dense toolbars.
Content
- Name the thing that turns on: Bold, Pin thread. Not Toggle bold.