BridgeHandbookDraft
For agents
Menu
ExperimentalmoleculeInputs

SegmentedControl

A pill switcher for two to five modes of one view, such as a date range.

import { … } from "@brdgapp/ui/components/segmented-control"

Usage

SegmentedControl picks one of two to five modes for a single view: a growth chart's 12, 26 or 52 weeks, or Light and Dark. One option is always selected. The usual mistake is using it to filter a list or to switch between different content, which are FilterChip and Tabs.

When to use

  • Switching how one view is shown: a time range, a sort direction, a theme.

When not to use

  • For different content under one heading. Use Tabs instead.
  • For filters that can be combined or turned off. Use FilterChip instead.
  • For more than five options. Use a menu.

Every control has a name

Every control says what it does to a screen reader. An icon-only button carries an aria-label naming the action ("Close", not "X"); a group of filters or a table has a name; a tooltip is never the only name.

Anatomy

  1. Track. A pill on --surface-secondary with a 1px border.

  2. Option. 12px SemiBold. The selected option sits on a raised white pill with a soft shadow.

Examples

Time range

The Outcomes growth chart's range.

Appearance

Settings → Appearance.

States

RestHoverFocus
Selected
Not selected
StateWhat happens
SelectedRaised pill, --text-primary.
Rest--text-muted; hover darkens.
Focus visible2px blue ring on the option.

Behavior

  • Built on Base UI ToggleGroup: each option reports aria-pressed, and arrow keys move between options.
  • Pressing the selected option does nothing, so something is always chosen.
  • Controlled: you pass value and onChange.

Do and don't

Do

Keep labels short and parallel: 12 weeks, 26 weeks, 52 weeks.

Don't

Mix an icon-only option with text options.

Content

  • Sentence case, one or two words per option.

Accessibility

  • aria-label on the control is required: it says what is being chosen ("Time range").
  • An icon-only option needs ariaLabel.
KeysAction
←→Move between options.
EnterSpaceSelect the focused option.

API reference

SegmentedControl

The switcher.

PropTypeDefaultDescription
options{ value, label, ariaLabel? }[]—Two to five options.
valuestring—The selected option.
onChange(value) => void—Called with the new option.
aria-labelstring—Required. What is being chosen.
classNamestring—Layout only.

Lineage

What it's built from and where it's used, read from the code. When you change it, check these too.

Built from
Nothing else in the package
Used by components
None
Used in patterns
Forms and validationSaving and unsaved changesNavigationKeyboard and commandsMetrics and explainers
Used in templates
Card dashboardSettings form

Known gaps

Where the code still differs from the system. Follow the system, not the gap.

  • Bridge OS's aria-label was optional. The package requires it, so a nameless control won't compile.

Sources

  • Bridge OS components.md → SegmentedControl; src/components/ui/segmented-control.tsx.