# 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

- 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 | Default | 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` | `false` | Disables every item. |

### SegmentedControl.Item

A `role='radio'` button. Carries `data-selected` and `data-disabled`.

Slot: `cl-segmented-control-item`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` |  | Identifies the item, compared with `Object.is`. |
| `disabled` | `boolean` | `false` | Disables this item. |

## Examples

### Billing period

```tsx
<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>
```

## Related

- [Tabs](/docs/components/tabs.md)
