On this page
SegmentedControl
Headless, unstyled single-select row of buttons, one always active. Follows the radio group pattern: role="radiogroup", role="radio" items, one tab stop, and arrow keys that move the selection.
Use for
- switching between a few mutually exclusive options
- a billing period toggle, such as monthly or annual
- a compact single choice shown as buttons instead of radios
Practices
| Guidance | Practice |
|---|---|
| Do | Name the group with aria-label or aria-labelledby on SegmentedControl.Root. |
| Do | Slide SegmentedControl.Indicator with its data-direction, which says whether the selection moved forward or backward. |
| Don’t | Use it when each option owns a panel of content. Use Tabs instead. |
API reference
SegmentedControl.Root
A div with role="radiogroup" that holds the selection and arrow-key navigation. Carries data-disabled.
| Prop | Type | Description |
|---|---|---|
value | Value | The selected value, when controlled. |
defaultValue | Value | The selected value on mount, when uncontrolled. |
onValueChange | (value: Value) => void | Called with the new value. Not called when the same item is chosen again. |
disabled | boolean | Disables every item.Default: false |
SegmentedControl.Item
A button with role="radio" and aria-checked. Carries data-selected and data-disabled. Arrow keys select as they move.
| Prop | Type | Description |
|---|---|---|
value | unknown | Identifies the option, compared with Object.is. Unique within the root. |
disabled | boolean | Sets aria-disabled. The item stays focusable. |
SegmentedControl.Indicator
A decorative span, aria-hidden, for the selection highlight. Carries data-direction.
Examples
Billing period
<SegmentedControl.Root aria-label='Billing period' defaultValue='monthly'>
<SegmentedControl.Item value='monthly'>Monthly</SegmentedControl.Item>
<SegmentedControl.Item value='annual'>Annual</SegmentedControl.Item>
</SegmentedControl.Root>