# 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

- 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 | 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 new value. Not called when the same item is chosen again. |
| `disabled` | `boolean` | `false` | Disables every item. |

### SegmentedControl.Item

A `button` with `role="radio"` and `aria-checked`. Carries `data-selected` and `data-disabled`. Arrow keys select as they move.

| Prop | Type | Default | 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

```tsx
<SegmentedControl.Root aria-label='Billing period' defaultValue='monthly'>
  <SegmentedControl.Item value='monthly'>Monthly</SegmentedControl.Item>
  <SegmentedControl.Item value='annual'>Annual</SegmentedControl.Item>
</SegmentedControl.Root>
```

## Related

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