Tabs API

Component status:: stable

Import

import { Tabs } from "@stratakit/structures";
// OR
import * as Tabs from "@stratakit/structures/Tabs";

Tabs.Provider

A set of tabs that can be used to switch between different views.

Tabs is a compound component with subcomponents exposed for different parts.

Example:

<Tabs.Provider>
  <Tabs.TabList>
    <Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>
    <Tabs.Tab id="tab-2">Tab 2</Tabs.Tab>
    <Tabs.Tab id="tab-3">Tab 3</Tabs.Tab>
  </Tabs.TabList>

  <Tabs.TabPanel tabId="tab-1">Tab 1 content</Tabs.TabPanel>
  <Tabs.TabPanel tabId="tab-2">Tab 2 content</Tabs.TabPanel>
  <Tabs.TabPanel tabId="tab-3">Tab 3 content</Tabs.TabPanel>
</Tabs.Provider>

The tabs and their panels are connected by matching the id prop on the Tabs.Tab component with the tabId prop on the Tabs.TabPanel component.

The Tabs component automatically manages the selected tab state. The initially selected tab can be set using defaultSelectedId. To take full control the selected tab state, use the selectedId and setSelectedId props together.

Note: Tabs should not be used for navigation; it is only intended for switching smaller views within an existing page.

children

Type: ReactNode (optional)

defaultSelectedId

Type: string | null | undefined (optional)

The id of the tab whose panel is currently visible. If it’s undefined, it will be automatically set to the first enabled tab.

selectedId

Type: string | null | undefined (optional)

The id of the tab whose panel is currently visible. If it’s undefined, it will be automatically set to the first enabled tab.

selectOnMove

Type: boolean | undefined (optional)

Default: false

setSelectedId

Type: ((selectedId: string | null | undefined) => void) | undefined (optional)

Function that will be called when the selectedId state changes.

Tabs.TabList

Base element: <div>

A simple container for the tab buttons. Should be used as a child of Tabs.Provider and consist of the individual Tabs.Tab components.

Example:

<Tabs.TabList>
  <Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>
  <Tabs.Tab id="tab-2">Tab 2</Tabs.Tab>
  <Tabs.Tab id="tab-3">Tab 3</Tabs.Tab>
</Tabs.TabList>

tone

Type: "neutral" | "accent" | undefined (optional)

Default: "neutral"

Additional props

render

Tabs.Tab

Base element: <button>

An individual tab button that switches the selected tab panel when clicked.

Should be used as a child of Tabs.TabList and be paired with a Tabs.TabPanel, connected using an id.

Example:

<Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>

Start and end icons can be added by passing Icon as children.

<Tabs.Tab id="tab-1">
  <Icon href={…} />
  Tab 1
  <Icon href={…} />
</Tabs.Tab>

id

Type: string (required)

The globally unique id of the tab. This will be used to identify the tab and connect it to the corresponding Tabs.TabPanel via the tabId.

The selectedId state of Tabs.Provider will also be based on this id.

Additional props

Tabs.TabPanel

Base element: <div>

The actual content of a tab, shown when the tab is selected. Should be used as a child of Tabs.Provider. The tabId prop should match the id prop of the corresponding Tabs.Tab component.

Example:

<Tabs.TabPanel tabId="tab-1">Tab 1 content</Tabs.TabPanel>

tabId

Type: string | null (required)

The id of the tab controlling this panel. This connection is used to assign the aria-labelledby attribute to the tab panel and to determine if the tab panel should be visible.

This link is automatically established by matching the order of Tab and TabPanel elements in the DOM. If you’re rendering a single tab panel, this can be set to a dynamic value that refers to the selected tab.

focusable

Type: boolean | undefined (optional)

Default: true

Determines if Focusable features should be active on non-native focusable elements.

Note: This prop only turns off the additional features provided by the Focusable component. Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability, but without added features such as improved autoFocus, accessibleWhenDisabled, onFocusVisible, etc.

unmountOnHide

Type: boolean | undefined (optional)

Default: false

When set to true, the content element will be unmounted and removed from the DOM when it’s hidden.