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