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

GuidancePractice
DoWrap the panels in Tabs.Panels so they share one grid cell and can animate in and out.
DoPass keepMounted to a panel whose state must survive being hidden.
Don’tPass orientation. The styled tabs are horizontal only; the headless primitive supports vertical.
Don’tUse 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

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

PropTypeDescription
valuestringIdentifies the tab. Matches a panel's value.
disabledbooleanDisables 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

PropTypeDescription
valuestringMatches a panel's value.
disabledbooleanDisables 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

PropTypeDescription
valuestringMatches a tab's value.
keepMountedbooleanKeeps 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>