# Tabs

Headless, unstyled tabs: a `tablist` of tabs that each show one panel. Arrow keys move between tabs, and focus selects a tab unless `activationMode` is `manual`. A hidden panel unmounts its children after its exit animation.

## Use for

- switching between views in the same area of a page
- parallel sections of settings shown one at a time
- tabbed content with a sliding selection indicator

## Practices

- Do: Give each `Tabs.Panel` the `value` of its tab. The tab and panel ids are paired from it.
- Do: Pass `keepMounted` to a panel whose state must survive being hidden. Its children unmount otherwise.
- Do: Slide panels with `--cl-tab-transition-direction`, and the indicator with `data-direction`.
- Don't: Pass `id` to a tab or panel. The primitive owns it and drops yours.
- Don't: Put `Tabs.Trigger` in `Tabs.List`. Use `Tabs.Tab` there; `Tabs.Trigger` is for a button outside the list and has no arrow-key navigation.
- Don't: Use it for a choice that does not own a panel. Use `SegmentedControl` instead.

## API reference

### Tabs.Root

Holds the selected tab and the direction it last moved. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The selected tab, when controlled. |
| `defaultValue` | `string` | `''` | The selected tab on mount, when uncontrolled. |
| `onValueChange` | `(value: string) => void` |  | Called with the new tab value. Not called when the same tab is chosen again. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Which arrow keys move between tabs. |
| `activationMode` | `'automatic' \| 'manual'` | `'automatic'` | Whether focusing a tab selects it, or `Enter`, `Space` or a click must. |

### Tabs.List

A `div` with `role="tablist"` and `aria-orientation`, with one tab stop and arrow-key navigation.

### Tabs.Tab

A `button` with `role="tab"`, `aria-selected` and `aria-controls`, inside `Tabs.List`. Carries `data-selected` and `data-disabled`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Identifies the tab. Matches a `Tabs.Panel` value. |
| `disabled` | `boolean` |  | Sets `disabled` and `aria-disabled`, and blocks selection. |

### Tabs.Trigger

A standalone `button` with `role="tab"` that selects its tab on click, for use outside `Tabs.List`, such as in a sidebar. Carries `data-selected` and `data-disabled`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Identifies the tab. Matches a `Tabs.Panel` value. |
| `disabled` | `boolean` |  | Sets `aria-disabled` and blocks selection. The trigger stays focusable. |

### Tabs.Panel

A `div` with `role="tabpanel"`, labelled by its tab. Carries `data-hidden`, `data-open`, `data-closed`, `data-starting-style` and `data-ending-style`, and `--cl-tab-transition-direction`. A leaving panel is `inert` and its children freeze. The first selected panel shows without an enter animation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The tab value that shows this panel. |
| `keepMounted` | `boolean` |  | Renders the children while the panel is hidden. |

### Tabs.Indicator

A decorative `span`, `aria-hidden`, for the selection highlight. Carries `data-direction`. Position it with CSS anchor positioning.

## Examples

### Tabs with an indicator

```tsx
<Tabs.Root defaultValue='account'>
  <Tabs.List>
    <Tabs.Tab value='account'>Account</Tabs.Tab>
    <Tabs.Tab value='security'>Security</Tabs.Tab>
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Panel value='account'>Account settings</Tabs.Panel>
  <Tabs.Panel value='security'>Security settings</Tabs.Panel>
</Tabs.Root>
```

## Related

- [SegmentedControl](/docs/components/segmented-control.md)
- [Accordion](/docs/primitives/accordion.md)
