Pick one of a few mutually-exclusive options shown as connected segments — the labeled, horizontal alternative to a stack of radios; it sets a value, it does not switch views (that is Tabs). Built as a radiogroup of visually-hidden native radios, so arrow keys move selection and exactly one segment stays checked with no JS.
Real wiring, no demo chrome: click or focus a segment and arrow between options — native radios do all of it. A disabled segment stays visible but is skipped.
One sm/md/lg dialect — track height and label size follow size.interactive, while button-like segment inset scales through space.2 / space.3 / space.4. The selected fill sits half of space.1 inside the track.
| Example | Size | Modifier | Height | Usage |
|---|---|---|---|---|
| Small | --sm | size.interactive.sm | Dense surfaces: toolbars, filter bars | |
| Medium | ds-segmented | size.interactive.md | The default — most surfaces | |
| Large | --lg | size.interactive.lg | High-emphasis, touch targets |
State lives on the segment. Each row applies it to the first segment; real drivers set every state and the demo classes force hover and focus here.
| Example | State | Driver | Roles | Usage |
|---|---|---|---|---|
| Rest | — | text.secondary | An option not currently chosen | |
| Hover | :hover | text.primary | The text lifts; the fill stays reserved for selection | |
| Selected | :has(:checked) | selection.bgtext.primary | The persistent chosen segment — exactly one per group | |
| Focus | :focus-visible | focus.ring | Keyboard focus on the segment | |
| Disabled | :disabled | action.disabled.text | Visible but not pickable |
A segmented control answers one question: which mode, from two to five that fit on a line.
| Verdict | Rule |
|---|---|
| Do | Give the group an accessible name via aria-label or aria-labelledby — the segments are the radios' labels. |
| Do | Seed an initial selection — exactly one segment is checked at all times; never render an all-unselected group. |
| Do | Keep role="radiogroup" with native radios so selection is announced as "radio, selected", not as buttons. |
| Don’t | Stretch it past 2–5 short options of similar length — more or longer belongs in a Select, and switching views is Tabs. |
| Don’t | Signal selection with hue alone — the filled cell and native checked state carry the choice without depending on brand color. |