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 inset tray, alt2 border, radius, and selected fill are shared with ToggleGroup and ButtonGroup.
- 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.
- More than five options or long labels—use
Select or Combobox.
- Route changes—use
TabNav.
- Form wizards requiring validation before switching—use explicit next/back patterns.
- Binary on/off toggles—use
Switch or IconToggle.
- 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").
- 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.
- Width. Controls keep their intrinsic width in flex layouts. Use
fullSpan only when every segment should share the available width.
Do
- 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.
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.
