SegmentedControl
A row of mutually exclusive options with a sliding indicator under the selected one. A role='radiogroup' with one tab stop; the arrow keys move and select at once.
Use for
- switching between a few views or modes, such as monthly and yearly billing
- a single choice among two to four short options
Practices
| Guidance | Practice |
|---|---|
| Do | Give the root an accessible name with aria-label or aria-labelledby. |
| Don’t | Use it to switch between panels of content. Use Tabs instead. |
API reference
SegmentedControl.Root
Holds the selected value and renders a div with the indicator (cl-segmented-control-indicator). Carries data-disabled. Typed by the value, string by default.
Slot: cl-segmented-control-root
| 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 newly selected value. |
disabled | boolean | Disables every item.Default: false |
SegmentedControl.Item
A role='radio' button. Carries data-selected and data-disabled.
Slot: cl-segmented-control-item
| Prop | Type | Description |
|---|---|---|
value | unknown | Identifies the item, compared with Object.is. |
disabled | boolean | Disables this item.Default: false |
Examples
Billing period
<SegmentedControl.Root aria-label='Billing period' value={period} onValueChange={setPeriod}>
<SegmentedControl.Item value='month'>Monthly</SegmentedControl.Item>
<SegmentedControl.Item value='annual'>Yearly</SegmentedControl.Item>
</SegmentedControl.Root>