Toggle Button
Last Updated: September 2026Toggle buttons are controls that allow users to turn a control, mode, or portion of the UI on or off. They support both labeled and icon only variants as well as various sizes for flexibility in application.
Source CodeAnatomy
link- 1Optional Container Border
- 2Icon
- 3Prefix
- 4Label
- 5Suffix
Variants
linkLabeled
Text label with optional prefix icon. Clearest for most toggles.
Icon-only
prefixIcon without children. Requires aria-label.
Pressed
defaultPressed or controlled pressed shows the active state.
Outline off
outline={false} removes the border on the unpressed state.
Sizes
linkToggle buttons support 3 sizes: S, M, and L.
Usage Guidelines
linkWhen to use
- •To toggle a binary setting on or off (bold, starred, filtered).
- •When pressed state should stay visible after the click.
- •In toolbars where several independent toggles sit side by side.
When not to use
- •For exclusive options in a segmented set — use ButtonGroup.
- •For one-shot actions (save, submit) — use Button.
- •For on/off settings with a clear track affordance — consider a Switch pattern.
Use toggles for durable on/off state the user can reverse.
Don't use ToggleButton for one-shot actions like Save or Submit.
Provide aria-label on icon-only toggles.
Don't ship icon-only toggles without an accessible name.
Behaviors
linkPressed state
- •Use pressed / defaultPressed plus onPressedChange for controlled or uncontrolled state.
- •Pressed is exposed to assistive tech as aria-pressed.
Disabled state
- •Set disabled=true to prevent toggling.
- •Disabled toggles keep their pressed appearance but are not interactive.
Content Guidelines
linkLabels
- •Name the state or attribute being toggled ('Bold', 'Starred'), not the action ('Click').
- •Keep labels short — one or two words.
Icons
- •prefixIcon reinforces the label; suffixIcon only renders when children are present.
- •Icon-only toggles need a clear, standard symbol plus aria-label.
Accessibility
linkText & Labels
- •Provide visible text or aria-label.
- •Icon-only toggles must include aria-label.
ARIA attributes
- •aria-pressed reflects the pressed state.
- •value can associate the toggle with a group when needed.
Keyboard Support
- •Tab → focus.
- •Space / Enter → toggle pressed state.
WCAG Compliance Standards
FAQs
linkToggleButton vs ButtonGroup?
ToggleButton is for independent on/off state. ButtonGroup is for choosing among related options (single or multi-select).
How do I control the pressed state?
Pass pressed and onPressedChange for controlled usage, or defaultPressed for uncontrolled.
Can I put a suffix icon on an icon-only toggle?
No — suffixIcon only renders when children (a label) are present. Use prefixIcon for icon-only.