Use cases
- Toolbar formatting (
variant="default") — bold, italic, underline in a text editor. - View switchers — grid vs list layout toggle.
- Feature flags in a settings panel — enable/disable a capability.
- Multi-select groups (
ToggleGroup type="multiple") — pick multiple text formats at once. - Single-select groups (
ToggleGroup type="single") — alignment, sort direction.
When NOT to use
- Binary on/off with a track visual — use Switch.
- Selecting from a long list — use Select or Tabs.
- Navigation between pages — use Tabs or a sidebar.
Variants
| Variant | Use when |
|---|---|
default | Toolbar buttons with a subtle pressed background. |
outline | Standalone toggle where the border provides affordance. |
Composition
- Pair icon + text for clarity. Icon-only toggles need an
aria-label. ToggleGroupwithtype="single"enforces mutual exclusion (like radio buttons but visually as buttons).ToggleGroupwithtype="multiple"allows any combination (like checkboxes but visually as buttons).disabledon an individual item prevents toggling without affecting siblings.
Related
- Switch — binary toggle with track visual.
- Tabs — tabbed content switching.
- RadioGroup — single selection in a form context.