# Tabs

Horizontal tabs that switch between panels, with a sliding indicator under the selected tab. The arrow keys move between tabs. A hidden panel unmounts its children once its exit animation ends.

## Use for

- switching between panels of content on one page
- a tab bar, such as Members and Invitations
- a tab button outside the tab list, such as in a sidebar

## Practices

- Do: Wrap the panels in `Tabs.Panels` so they share one grid cell and can animate in and out.
- Do: Pass `keepMounted` to a panel whose state must survive being hidden.
- Don't: Pass `orientation`. The styled tabs are horizontal only; the headless primitive supports vertical.
- Don't: Use tabs to pick a value, such as a billing period. Use `SegmentedControl` instead.

## API reference

### Tabs.Root

Holds the selected tab and renders a `div`.

Slot: `cl-tabs-root`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | The selected tab, when controlled. |
| `defaultValue` | `string` | `''` | The selected tab on mount. |
| `onValueChange` | `(value: string) => void` |  | Called with the newly selected tab. |
| `activationMode` | `'automatic' \| 'manual'` | `'automatic'` | `automatic` selects a tab when it gets focus; `manual` waits for Enter or Space. |

### Tabs.List

The `role='tablist'`, with the indicator (`cl-tabs-indicator`) under the selected tab.

Slot: `cl-tabs-list`

### Tabs.Tab

A `role='tab'` button in the list, with roving focus. Carries `data-selected` and `data-disabled`.

Slot: `cl-tabs-tab`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Identifies the tab. Matches a panel's `value`. |
| `disabled` | `boolean` |  | Disables the tab with `aria-disabled`, keeping it focusable. |

### Tabs.Trigger

A standalone button outside `Tabs.List` that selects a panel. Not part of the arrow-key navigation. Carries `data-selected` and `data-disabled`.

Slot: `cl-tabs-trigger`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Matches a panel's `value`. |
| `disabled` | `boolean` |  | Disables the trigger. |

### Tabs.Panels

Stacks the panels in one grid cell so they can animate in and out.

Slot: `cl-tabs-panels`

### Tabs.Panel

A `role='tabpanel'` labelled by its tab. Carries `data-open`, `data-closed` while leaving, and `data-hidden`, and sets `--cl-tab-transition-direction` to `1` or `-1`.

Slot: `cl-tabs-panel`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` |  | Matches a tab's `value`. |
| `keepMounted` | `boolean` |  | Keeps the children rendered while the panel is hidden. |

## Examples

### Two tabs

```tsx
<Tabs.Root defaultValue='members'>
  <Tabs.List>
    <Tabs.Tab value='members'>Members</Tabs.Tab>
    <Tabs.Tab value='invitations'>Invitations</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panels>
    <Tabs.Panel value='members'>{members}</Tabs.Panel>
    <Tabs.Panel value='invitations'>{invitations}</Tabs.Panel>
  </Tabs.Panels>
</Tabs.Root>
```

## Related

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