An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:SegmentedControl authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-28 owners: [cixzhang] review_triggers: [ public-api, behavior, layout, interaction, motion, theming, styling, accessibility, visual, react-runtime, compatibility, ] verified_by: [ packages/core/src/SegmentedControl/SegmentedControl.test.tsx, packages/core/src/SegmentedControl/tests/SegmentedControl.interaction.browser.spec.ts, packages/core/src/SegmentedControl/useSegmentedSelectionMotion.test.ts, packages/core/src/SegmentedControl/useSegmentedTouchTracking.test.ts, packages/core/src/RadioList/tests/RadioGroup.a11y.test.tsx, packages/core/src/RadioList/tests/RadioGroup.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, ] modules: [] families: [] design_specs: [design:user-states, design:bidirectionality, design:reduced-motion] architecture: [ architecture:component-size-cascade, architecture:component-style-authoring, architecture:component-theming-surface, architecture:interaction-modality, architecture:public-component-api, ] contributing: [] system_specs: [ spec:AST-020, spec:AST-020/FR9, spec:AST-085, spec:AST-094, spec:AST-094/FR4, spec:AST-094/FR11, spec:AST-094/FR13, spec:AST-094/FR43, spec:AST-094/FR45,
]
SegmentedControl component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. SegmentedControl takes label, value, onChange, size, layout, isDisabled, disabledMessage, base props, and SegmentedControlItem children. |
| Behavior | A role="radiogroup" named by label with one Tab stop; arrow keys, Home, and End move focus between enabled segments, wrap, and select the segment they land on. Tabbing in never changes the value. Every change of selection slides the selected surface, and a drag from the selected segment carries it with any pointer until the lift commits. |
| End-user impact | People switch between a few modes with one click or arrow press, and the control shrinks with its row by truncating labels. A disabled control keeps one Tab stop. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A drag now commits at the lift on the nearest segment, where a press used to select only on a click inside a segment; onChange still fires once per commit, and a lift outside the control still selects nothing (patch, the touch presentation batch). A caller onFocus or onBlur can cancel built-in focus behavior, caller handlers run while disabled, and a caller aria-describedby is dropped; all are listed under Current-state impact. |
| Review checks | Reject more than one Tab stop, a value change on Tab entry, arrows that land on a disabled segment, a control that overflows its container when segments have labels, or a selection while disabled. |
| Governing rules | WAI-ARIA radio group pattern; spec:AST-020 FR9, FR15, DEC-5; spec:AST-094 FR4, FR11, FR13, FR43; design:reduced-motion; spec:AST-085 FR1, FR2, FR5, FR7; design:user-states DR1–DR3 (through SegmentedControlItem); design:bidirectionality DR6; architecture:component-size-cascade INV3–INV5; architecture:interaction-modality INV1; architecture:public-component-api INV5, INV7. |
This table is a review projection; the body below is authoritative.
Intent
SegmentedControl presents a group of mutually exclusive choices through
SegmentedControlItem children. It owns the radiogroup, its single Tab stop and
arrow-key selection, the group's size, layout, and disabled state, and the
consumer theming anatomy. Consumer usage lives in SegmentedControl.doc.mjs.
Compatibility and migration
- Released default preserved:
yes;size="md",layout="hug", not disabled - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: controlled; selection is
valueandonChange - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The radiogroup control and its current
segmented-controltheming target. - The roving Tab stop, arrow, Home, and End navigation, and selection-follows-focus.
- Group size, layout, disabled state, and the disabled-reason tooltip.
- The keyboard hint shown on first keyboard focus.
- The consumer theming anatomy, including the segment target's mapping.
Does not own / non-goals
- Each segment's radio semantics, click selection, label and icon rendering,
item disabled state, and paint — owned by
component:SegmentedControlItem. - The artwork supplied through an item's
iconprop — owned by the caller. - A separate anatomy part or target for selected state; selection is state on the segment target.
- A visible control-level label; the control's required
labelis its accessible name and is not rendered as visual anatomy. - Page navigation — use TabList; no SegmentedControl requirement covers it.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Value | string | The selected segment's value. | Always. | required | component:SegmentedControl |
Stable | A value no segment carries selects nothing; the first segment not disabled by its own isDisabled becomes the Tab stop. |
| Size | sm, md, lg |
Segment height and text size. | Always. | Inherited size, else md |
component:SegmentedControl |
Stable | TypeScript rejects other values. |
| Layout | hug, fill |
Content-sized control, or full width with equal segments. | Always. | hug |
component:SegmentedControl |
Stable | TypeScript rejects other values. |
| Disabled | off, on, on with reason | Blocks selection on every segment. | A reason applies only with isDisabled. |
off | component:SegmentedControl |
Stable | A reason without isDisabled renders nothing. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The radiogroup container carries the current segmented-control target with data-size, sets aria-label to label, and renders its supplied children. |
Current source, docs, and tests |
| FR2 | The group is one Tab stop: the selected segment, or, when the value matches no segment, the first segment not disabled by its own isDisabled (in a disabled group that segment keeps the stop, FR7); a disabled selected segment MUST keep the Tab stop (spec:AST-085 FR1). ArrowLeft and ArrowRight move focus between enabled segments in the visual direction, flipping in right-to-left layouts (design:bidirectionality DR6), and wrap; Home and End jump to the ends; ArrowUp and ArrowDown do nothing. Disabled segments are skipped. |
WAI-ARIA radio group pattern; current tests; design:bidirectionality DR6 |
| FR3 | When arrow, Home, or End navigation moves focus to an enabled segment, that segment's value is passed to onChange if it differs. A tap selects through the segment's click when its lift lands on that segment; a drag commits at the lift on the segment nearest the pointer, its padding and the gaps between segments included (FR13); a lift outside the control selects nothing (spec:AST-020 FR9, DEC-5). Focus entering the group from outside never changes the value. |
WAI-ARIA radio group pattern; current tests; spec:AST-020 FR9, DEC-5 |
| FR4 | A caller onKeyDown runs before built-in navigation and can cancel it with preventDefault(); a caller onFocus runs before selection-follows-focus. On first keyboard focus an ephemeral hint naming the arrow keys appears at the focused segment and dismisses on the first arrow press, a timeout, or blur. Built-in focus behavior MUST NOT be cancellable except where the public API promises it (architecture:public-component-api INV7). Implementation gap: a caller onFocus that calls preventDefault() also cancels the hint, the Tab-stop sync, and selection-follows-focus, and a caller onBlur that does so cancels the hint's blur dismissal. |
Current source and tests; architecture:public-component-api INV7 |
| FR5 | hug sizes the control to its segments; when any segment shows a visible label, the control never exceeds its container and labelled segments shrink and truncate. A control of only icon-only segments keeps its size. fill stretches the control to its container and gives segments equal shares that can shrink and truncate. |
Current tests |
| FR6 | Size resolves from an explicit size, then the nearest size provider, then md, and reaches every segment. |
architecture:component-size-cascade INV3–INV5; current source |
| FR7 | isDisabled sets aria-disabled on the radiogroup, disables every segment, dims the control to half opacity, and blocks selection. The group MUST keep a Tab stop while disabled, placed as in FR2, and pointer events stay on (spec:AST-085 FR1, FR7). With disabledMessage, a reason tooltip opens on hover and keyboard focus; the reason MUST describe the focusable segment (spec:AST-085 FR5, FR7). Implementation gap: caller handlers on the radiogroup, such as onKeyDown, still run while disabled (spec:AST-085 FR2). |
spec:AST-085; current tests |
| FR8 | The radiogroup owns role, aria-label (from label), aria-disabled, and data-size; a caller value for any of them is replaced. Other base props reach the radiogroup, and ref reaches it. Implementation gap: a caller aria-describedby is replaced, by the disabled-reason id or by nothing, against architecture:public-component-api INV5. |
architecture:public-component-api INV5; current source and tests |
| FR9 | Under every pointer, a change of selection slides the selected surface from the old segment to the new one as one surface, the radiogroup's ::before, animating transform and opacity only. Under a touch presentation, a change that a tap, a click, a key or the program starts settles on the same spring as a drag's release, from rest: under touch, SegmentedControl's main interaction is a gesture (spec:AST-094 FR45). Without a touch presentation, a change that a click, a key or the program starts slides on the theme's duration and easing tokens, as released. A drag's release settles on that spring from the release velocity (FR10, FR13). |
Owner direction; spec:AST-094 FR13; current source and tests |
| FR10 | A drag's release settles on the internal segmented.* motion roles with UIKit's measured values, starting at the release velocity under every pointer, with the theme's character and tempo shaping the spring (spec:AST-094 FR4, FR45, DEC-15; thresholds internal under spec:AST-002 FR3). Under Reduce Motion the old surface fades out in place as the new one fades in (design:reduced-motion DR1–DR3). With a fine pointer under Reduce Motion, the theme's transition shows the change. Implementation gap: under a mouse or a pen a drag's release slides on the theme's duration. |
UIKit measurements (iOS 26.2); design:reduced-motion DR1–DR3; current tests |
| FR11 | Under a finger, a held unselected segment paints the pressed overlay on its part, as under a mouse (design:user-states DR1); no theme role changes or dims it. |
design:user-states DR1; current tests |
| FR12 | During a drag of the selected surface, the selected label's colour follows the surface, with an internal hysteresis around each boundary; the weights change at the lift. A tap selects through the browser's click (spec:AST-094 FR11). |
Owner decision (weights at the lift); current tests |
| FR13 | Under a finger, a drag from the selected segment carries the selected surface with the finger, within an internal overshoot past the end segments, and the lift commits the segment nearest the finger through that segment's click; a drag that starts on another segment leaves the surface in place and commits where it lifts, as a menu's press-tracking slide commits where it lifts (spec:AST-094 FR26–FR28). A mouse and a pen drag the same way (spec:AST-094 FR43). Under Reduce Motion the surface still follows the pointer, as direct movement (design:reduced-motion), and a finger's release cross-fades; under a fine pointer a mouse's or a pen's release lands at once (DR3). A lift outside the control commits nothing (FR3). |
spec:AST-094 FR26–FR28, FR43; design:reduced-motion; current tests |
Allowed variation
- AV1 — Segments. A segment may render its visible label, an icon and label, or an icon while the required label supplies the accessible name.
- AV2 — Theme paint. Themes may restyle the control and segments through their targets and the reflected states.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Hug, labelled | Content-sized; capped at the container; labels truncate. | Size. |
| Fill | Full width; equal segments. | — |
| Unmatched value | The first segment not disabled by its own isDisabled is the Tab stop; Tab-in changes nothing. |
— |
| Disabled with reason | Selected segment focusable; reason tooltip; no selection. | — |
| Disabled, no reason | Selected segment focusable; no selection. | — |
Transformation and precedence order
- ORD1 — Keydown and focus. Caller
onKeyDown, then the hint, then navigation unless prevented; calleronFocus, then the hint, the Tab-stop sync, and selection-follows-focus (today also cancelled by a preventedonFocus, FR4 gap). - ORD2 — Tab stop. The selected segment; for a value that matches no
segment, the first segment not disabled by its own
isDisabled. A disabled selected segment, or a segment of a disabled control, keeps the stop (FR2, FR7).
Performance and resources
- PR1 — Bounded resources. One roving-focus handler, one hint, and the disabled-reason tooltip's pointer and focus listeners on the radiogroup per control, plus, through the tooltip's layer, the shared gesture counter's document listeners, installed once per page; segments share the press controller's window and document listeners.
- PR2 — The touch presentation adds no element. SegmentedControl is a
repeated control, so it keeps the strict element budget
(
architecture:component-style-authoringINV7): the slide uses the radiogroup's::before.
Accessibility contract
- AR1 — Group semantics.
role="radiogroup"named bylabel; segments followcomponent:SegmentedControlItemAR1. - AR2 — Keyboard. FR2 and FR3.
- AR3 — Disabled reason. FR7.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Control | Presents the current grouped choice container. | Current source and public docs | Supporting | FR1, FR5 |
| Segment | Presents one mutually exclusive choice and its item states. | Current source and public docs | Prominent | component:SegmentedControlItem FR1 |
| Label | Identifies a segment visually when not hidden. | Current source and public docs | Prominent | component:SegmentedControlItem FR3 |
| Icon | Presents optional caller-supplied artwork within a segment. | Caller-supplied content | Supporting | component:SegmentedControlItem FR3 |
design:user-states governs the segments' pressed overlay and its
selected-segment exception (component:SegmentedControlItem FR5), and
design:bidirectionality DR6 governs the arrow-key direction (FR2). Selection is a state of Segment, not a
separate anatomy part. The consumer
docs declare both targets on SegmentedControl, so the map below covers the
segment parts as well.
Theming anatomy
{
"Control": {"target": "segmented-control"},
"Segment": {"target": "segmented-control-item"},
"Label": {"inherits": "segmented-control-item"},
"Icon": {"inherits": "segmented-control-item"}
}
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, inherited parts, and state-on-target rules.spec:AST-085owns disabled focusability, reasons, and callbacks; FR7 records the gap.component:SegmentedControlItemowns each segment.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | SegmentedControl.test.tsx rendering, size, and data-testid cases; RadioGroup.a11y.test.tsx and RadioGroup.a11y.chromium.spec.ts (in RadioList/__tests__) segmented-group-* states |
Control with several segments; sizes | Lost group semantics or name fails. Evidence gap: no test asserts the segmented-control target or data-size. |
audit:SegmentedControl/anatomy |
| FR2, FR3, ORD2, AR2 | SegmentedControl.test.tsx keyboard-navigation, unmatched-value and Tab-stop cases; RadioGroup.a11y.test.tsx and RadioGroup.a11y.chromium.spec.ts (in RadioList/__tests__) segmented-group-* states; the radio-group pattern's aborted-press check on segmented-option-unselected; the segmented-group-selected-rtl state's arrow round trip under dir="rtl"; SegmentedControl.interaction.browser.spec.ts slide-off cases for a finger and a mouse, with focus in the group or not |
Arrows, wrap, Home, End; Tab-in with an unmatched or disabled selection | A value change on Tab entry, no wrap, or landing on a disabled segment fails. A press that slides off with focus outside the group and still selects fails. A press with focus already in the group that selects before its lift fails. | audit:SegmentedControl/accessibility |
| FR4, ORD1 | SegmentedControl.test.tsx container handler forwarding cases |
Caller onKeyDown, with and without preventDefault |
A caller key handler that cannot cancel navigation fails. Evidence gap: no test asserts the caller onFocus order or the keyboard hint. |
audit:SegmentedControl/behavior |
| FR5 | SegmentedControl.test.tsx layout cases |
Hug, fill, narrow row, icon-only | A control that overflows, or squeezes icon-only segments, fails. | audit:SegmentedControl/layout |
| FR6 | Evidence gap: no test asserts size precedence or its propagation | — | — | audit:SegmentedControl/layout |
| FR7, AR3 | SegmentedControl.test.tsx disabled and disabledMessage cases; RadioGroup.a11y.test.tsx and RadioGroup.a11y.chromium.spec.ts (in RadioList/__tests__) segmented-group-disabled and segmented-group-disabled-with-message states |
Group and item disabled; with reason | A selection while disabled, or a missing reason tooltip, fails. Evidence gap: no test asserts the half opacity, or caller handlers while disabled. The segmented-group-disabled state declares a Tab stop. |
audit:SegmentedControl/accessibility |
| FR8 | SegmentedControl.test.tsx role-override and data-testid cases |
Forwarded role | A forwarded prop that overrides the role fails. Evidence gap: no test asserts ref or a caller aria-describedby. |
audit:SegmentedControl/api |
| FR9, FR10, PR2 | useSegmentedSelectionMotion.test.ts slide, retarget, keyboard, Reduce Motion and fine-pointer cases; SegmentedControl.interaction.browser.spec.ts slide, measured-spring, Reduce Motion, busy-main-thread and mouse-click proofs in Chromium and WebKit |
a tap, a retarget, keyboard selection, Reduce Motion, a mouse | a second surface or added element, a Layout or Paint per frame, a slide under a touch presentation on a curve instead of the selection spring from rest, a click's, a key's or a program change's slide without a touch presentation off the theme's curve, a drag release under any pointer that settles from rest or on a theme curve instead of a spring from its velocity, or travel under Reduce Motion fails | audit:SegmentedControl/theming |
| FR11 | SegmentedControl.interaction.browser.spec.ts pressed-overlay proofs; PressedState.a11y.chromium.spec.ts segmented-control cases |
a held unselected segment, a held selected segment | an unselected segment without the pressed overlay, or a dim under the default theme fails | audit:SegmentedControl/theming |
| FR12, FR13 | useSegmentedSelectionMotion.test.ts and useSegmentedTouchTracking.test.ts drag, face and lift cases; SegmentedControl.interaction.browser.spec.ts drag, overshoot, hysteresis, tap-click, slide-off, Reduce Motion drag, mouse and pen proofs |
a hold, a drag, a release between segments, the end overshoot, a slow dither, a tap, a drag from another segment, a lift outside, Reduce Motion | a weight change mid-drag, a label that flips twice in a small dither, a commit anywhere but the segment nearest the finger, a commit after a lift outside, or a surface that stays put under Reduce Motion fails | audit:SegmentedControl/anatomy |
| PR1 | Evidence gap: no test asserts the absence of global listeners | — | — | audit:SegmentedControl/behavior |
| Target inventory | packages/core/src/theme/themingTargets.test.ts |
Control and item targets | A rendered class absent from the documented targets fails. | audit:SegmentedControl/theming |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and both current targets | Missing, extra, prefixed, or stale mappings fail repository validation. | audit:SegmentedControl/theming |
Current-state impact
- Focus handler cancellation (FR4). A caller
onFocusoronBlurthat callspreventDefault()cancels built-in focus behavior the public API does not promise to expose, againstarchitecture:public-component-apiINV7. - Caller handlers while disabled (FR7). Caller handlers on the radiogroup,
such as
onKeyDown, still run while disabled, againstspec:AST-085FR2. - Caller description (FR8). A caller
aria-describedbyon the control is replaced, againstarchitecture:public-component-apiINV5.
Decision log
- Keyboard model (FR2). The keyboard model is horizontal only: ArrowLeft
and ArrowRight skip disabled segments and select the segment they reach, and
ArrowUp and ArrowDown do nothing; horizontal movement follows the visual
direction (
design:bidirectionalityDR6).spec:AST-085leaves which items a composite's arrow keys visit to the composite.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables, examples, implementation steps, or system rules. It links to their owners.