On this page
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
| Guidance | Practice |
|---|---|
| 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 | Description |
|---|---|---|
value | string | The selected tab, when controlled. |
defaultValue | string | The selected tab on mount.Default: '' |
onValueChange | (value: string) => void | Called with the newly selected tab. |
activationMode | 'automatic' | 'manual' | automatic selects a tab when it gets focus; manual waits for Enter or Space.Default: 'automatic' |
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 | 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 | 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 | Description |
|---|---|---|
value | string | Matches a tab's value. |
keepMounted | boolean | Keeps the children rendered while the panel is hidden. |
Examples
Two tabs
<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>