Toggle group

Usage

Overview

ToggleGroup is a small cluster of pressed/unpressed buttons for mutually exclusive options where all choices are valuable to see at a glance. It overlaps semantically with SegmentedControl; reach for ToggleGroup when the design system calls for toggle-button semantics explicitly (toolbar groupings, icon-first density, optional multi-select). Use it when "pick one of a few" is the verb and the choices deserve equal visual weight. Visually it shares the same track fill (--color-fill-subtle), input edge (--color-border-input), radius (--radius-control), and selected wash (--alpha-12) as SegmentedControl and ButtonGroup. ButtonGroup keeps hairline dividers in place of this control's inset gap.

When to use

Two to five equally weighted modes (map layers, density, timeframe window).
Toolbar clusters where adjacent buttons should read as a group.
Contexts where Tabs would imply filtering a content list the group does not actually own.

When not to use

More than a handful of options—use Select or Combobox.
Navigation across routes—use Tabs.
Binary settings in forms with a prose label—use Switch.
A standalone labeled on/off control outside a group—use Button with toggle (Secondary selected fill) rather than nesting Button as a group item. Group children remain ToggleGroupItem.

Content guidelines

One or two words per item; parallel grammar across the group.
Avoid icon-only items unless the icons are already standardized in the product and a Tooltip provides the accessible name.

Behavior and states

Single vs. multi. Fix the mode per instance; don't swap between single-select and multi-select based on context—pressed-state semantics and assistive-tech output differ.
Default selection. Default to the safest or most common mode; a no-selection state is only valid when the pattern genuinely supports "none".
Width. Groups keep their intrinsic width in flex layouts. Set fullSpan when the group should fill the available width: text items divide the remaining width evenly, while icon-only items and items that collapse their label keep their own size and every item keeps its touch-target minimum. In a vertical group, text items fill the track width and icon-only items keep their size.
Icon-only items. A lone icon produces a square target at every supported size. Keep the accessible name in the icon title or an explicit label.
Collapsible labels. Use collapseUnselectedLabels only in narrow toolbars where every item has a distinct icon and aria-label. The selected label remains visible while inactive items retain square icon targets. Same shared 200ms ease-out motion and icon→label gap as SegmentedControl.

Best practices

Equal-width items when the options are equally weighted visually.
Align spacing and density with adjacent toolbar controls so the group reads as part of the toolbar.

Don't

Cram long labels; shorten or move to a Select.
Nest another toggle group inside an item. If two axes of choice exist, separate them.

Accessibility

Each item exposes pressed state; arrow keys navigate; names come from visible labels or explicit aria-label when icon-only. See Accessibility for the full contract.

Segmented control for the alternate grouped-control styling.
Tab menu for tab-strip filtering of a linked list.
Toolbar for placement context.

Toast / Accessibility

Toggle Group / API and Development

On this page

Toggle group

Usage

Overview

When to use

Two to five equally weighted modes (map layers, density, timeframe window).
Toolbar clusters where adjacent buttons should read as a group.
Contexts where Tabs would imply filtering a content list the group does not actually own.

When not to use

More than a handful of options—use Select or Combobox.
Navigation across routes—use Tabs.
Binary settings in forms with a prose label—use Switch.
A standalone labeled on/off control outside a group—use Button with toggle (Secondary selected fill) rather than nesting Button as a group item. Group children remain ToggleGroupItem.

Content guidelines

One or two words per item; parallel grammar across the group.
Avoid icon-only items unless the icons are already standardized in the product and a Tooltip provides the accessible name.

Behavior and states

Single vs. multi. Fix the mode per instance; don't swap between single-select and multi-select based on context—pressed-state semantics and assistive-tech output differ.
Default selection. Default to the safest or most common mode; a no-selection state is only valid when the pattern genuinely supports "none".
Width. Groups keep their intrinsic width in flex layouts. Set fullSpan when the group should fill the available width: text items divide the remaining width evenly, while icon-only items and items that collapse their label keep their own size and every item keeps its touch-target minimum. In a vertical group, text items fill the track width and icon-only items keep their size.
Icon-only items. A lone icon produces a square target at every supported size. Keep the accessible name in the icon title or an explicit label.
Collapsible labels. Use collapseUnselectedLabels only in narrow toolbars where every item has a distinct icon and aria-label. The selected label remains visible while inactive items retain square icon targets. Same shared 200ms ease-out motion and icon→label gap as SegmentedControl.

Best practices

Equal-width items when the options are equally weighted visually.
Align spacing and density with adjacent toolbar controls so the group reads as part of the toolbar.

Don't

Cram long labels; shorten or move to a Select.
Nest another toggle group inside an item. If two axes of choice exist, separate them.

Accessibility

Each item exposes pressed state; arrow keys navigate; names come from visible labels or explicit aria-label when icon-only. See Accessibility for the full contract.

Segmented control for the alternate grouped-control styling.
Tab menu for tab-strip filtering of a linked list.
Toolbar for placement context.

Toast / Accessibility

Toggle Group / API and Development

On this page