Skip to content
Mosaic
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

GuidancePractice
DoGive each Tabs.Panel the value of its tab. The tab and panel ids are paired from it.
DoPass keepMounted to a panel whose state must survive being hidden. Its children unmount otherwise.
DoSlide panels with --cl-tab-transition-direction, and the indicator with data-direction.
Don’tPass id to a tab or panel. The primitive owns it and drops yours.
Don’tPut 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’tUse 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.

PropTypeDescription
valuestringThe selected tab, when controlled.
defaultValuestringThe selected tab on mount, when uncontrolled.Default: ''
onValueChange(value: string) => voidCalled 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.

PropTypeDescription
valuestringIdentifies the tab. Matches a Tabs.Panel value.
disabledbooleanSets 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.

PropTypeDescription
valuestringIdentifies the tab. Matches a Tabs.Panel value.
disabledbooleanSets 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.

PropTypeDescription
valuestringThe tab value that shows this panel.
keepMountedbooleanRenders 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>