Segmented Control

Usage

Overview

SegmentedControl presents a few mutually exclusive options as a single merged-border surface: view density, time window, unit toggle, sort direction. It saves space versus separate buttons and reads as one control—closer to iOS segmented controls or Carbon button groups with merged borders than to tabs. The mental model is "pick one of these visible modes and apply it now". Use it when the full set fits comfortably and the choice is frequent enough that keeping all options visible beats hiding them in a menu. Its track fill (--color-fill-subtle), input edge (--color-border-input), radius (--radius-control), and selected wash (--alpha-12) are shared with ToggleGroup and ButtonGroup. ButtonGroup keeps hairline dividers in place of this control's inset gap.

When to use

Two to five short labels of equal importance that switch modes on the same page (hour / day / week, km / mi, list / grid).
Toolbar-adjacent filters where a dropdown would hide choices operators compare frequently.
Immediate-apply toggles without a separate submit step.

When not to use

More than five options or long labels—use Select or Combobox.
Route changes—use Tabs.
Form wizards requiring validation before switching—use explicit next/back patterns.
Binary on/off toggles—use Switch or IconToggle.

Content guidelines

Labels are one or two words; formatMessage; test translations to ensure no segment wraps into two lines.
Icons are optional; text-first is safer. If you use icons without text, ensure tooltips are always present.
Parallel grammar across segments ("Hour / Day / Week", not "Hour / Daily / The last week").

Behavior and states

Default selection. Reflect the safest or most common mode. An unselected state should be rare and only when valid.
Disabled segments. Explain why in a tooltip or helper text. A greyed segment with no reason invites support tickets.
Immediate apply. Change takes effect on selection; there's no separate submit. If side effects are expensive, debounce—don't show a loading UI inside the segment.
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. Labels animate open/closed at shared 200ms ease-out (--grouped-control-collapse-*) with the same icon→label gap as a static segment.
Strong selection. Set strong when the selected segment must read as the strongest mark on the track. It uses the transient surface (--color-bg-transient) and label (--color-fg-transient-default) with no border; hover and press add no paint, the focus ring is --focus-ring-color-transient, the same in light and dark mode, and a disabled selected segment keeps the regular disabled paint.
Width. Controls keep their intrinsic width in flex layouts. Use fullSpan only when every segment should share the available width.

Best practices

Limit segment count and test truncation on narrow dispatch side panels. What fits in a 320px inspector isn't what fits on a 1440px dashboard.
Keep segment widths roughly equal; the control reads as balanced peers.
Align with adjacent controls (filter bar, time range) for optical grouping.

Don't

Use for destructive mode switches without confirmation elsewhere. A click should not wipe data.
Mix unrelated domains ("Hour / Day / Week / Error") into one segmented control. Split into separate controls.
Place a segmented control inside a tab strip. The two mode-selectors compete and operators lose track of which one they're operating.

Accessibility

The selected state is exposed to assistive technology; arrow keys move the selection per platform expectation; labels give every segment an accessible name. See Accessibility for the full contract.

Toggle group for alternate toggle-group semantics (including multi-select).
Tab menu for tab-strip patterns without URL changes.
Select for longer option lists.

Secret / Accessibility

Segmented Control / API and Development

On this page

Segmented Control

Usage

Overview

When to use

Two to five short labels of equal importance that switch modes on the same page (hour / day / week, km / mi, list / grid).
Toolbar-adjacent filters where a dropdown would hide choices operators compare frequently.
Immediate-apply toggles without a separate submit step.

When not to use

More than five options or long labels—use Select or Combobox.
Route changes—use Tabs.
Form wizards requiring validation before switching—use explicit next/back patterns.
Binary on/off toggles—use Switch or IconToggle.

Content guidelines

Labels are one or two words; formatMessage; test translations to ensure no segment wraps into two lines.
Icons are optional; text-first is safer. If you use icons without text, ensure tooltips are always present.
Parallel grammar across segments ("Hour / Day / Week", not "Hour / Daily / The last week").

Behavior and states

Default selection. Reflect the safest or most common mode. An unselected state should be rare and only when valid.
Disabled segments. Explain why in a tooltip or helper text. A greyed segment with no reason invites support tickets.
Immediate apply. Change takes effect on selection; there's no separate submit. If side effects are expensive, debounce—don't show a loading UI inside the segment.
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. Labels animate open/closed at shared 200ms ease-out (--grouped-control-collapse-*) with the same icon→label gap as a static segment.
Strong selection. Set strong when the selected segment must read as the strongest mark on the track. It uses the transient surface (--color-bg-transient) and label (--color-fg-transient-default) with no border; hover and press add no paint, the focus ring is --focus-ring-color-transient, the same in light and dark mode, and a disabled selected segment keeps the regular disabled paint.
Width. Controls keep their intrinsic width in flex layouts. Use fullSpan only when every segment should share the available width.

Best practices

Limit segment count and test truncation on narrow dispatch side panels. What fits in a 320px inspector isn't what fits on a 1440px dashboard.
Keep segment widths roughly equal; the control reads as balanced peers.
Align with adjacent controls (filter bar, time range) for optical grouping.

Don't

Use for destructive mode switches without confirmation elsewhere. A click should not wipe data.
Mix unrelated domains ("Hour / Day / Week / Error") into one segmented control. Split into separate controls.
Place a segmented control inside a tab strip. The two mode-selectors compete and operators lose track of which one they're operating.

Accessibility

The selected state is exposed to assistive technology; arrow keys move the selection per platform expectation; labels give every segment an accessible name. See Accessibility for the full contract.

Toggle group for alternate toggle-group semantics (including multi-select).
Tab menu for tab-strip patterns without URL changes.
Select for longer option lists.

Secret / Accessibility

Segmented Control / API and Development

On this page