Tabs

A component for toggling between related panels on the same page.

import * as React from 'react';
import { Tabs } from '@base-ui-components/react/tabs';
import styles from './index.module.css';

export default function ExampleTabs() {
  return (
    <Tabs.Root className={styles.Tabs} defaultValue="overview">
      <Tabs.List className={styles.List}>
        <Tabs.Tab className={styles.Tab} value="overview">
          Overview
        </Tabs.Tab>
        <Tabs.Tab className={styles.Tab} value="projects">
          Projects
        </Tabs.Tab>
        <Tabs.Tab className={styles.Tab} value="account">
          Account
        </Tabs.Tab>
        <Tabs.Indicator className={styles.Indicator} />
      </Tabs.List>
      <Tabs.Panel className={styles.Panel} value="overview">
        <OverviewIcon className={styles.Icon} />
      </Tabs.Panel>
      <Tabs.Panel className={styles.Panel} value="projects">
        <ProjectIcon className={styles.Icon} />
      </Tabs.Panel>
      <Tabs.Panel className={styles.Panel} value="account">
        <PersonIcon className={styles.Icon} />
      </Tabs.Panel>
    </Tabs.Root>
  );
}

function OverviewIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="40" height="40" viewBox="0 0 30 30" fill="currentcolor" {...props}>
      <path d="M 6 4 C 4.895 4 4 4.895 4 6 L 4 12 C 4 13.105 4.895 14 6 14 L 12 14 C 13.105 14 14 13.105 14 12 L 14 6 C 14 4.895 13.105 4 12 4 L 6 4 z M 18 4 C 16.895 4 16 4.895 16 6 L 16 12 C 16 13.105 16.895 14 18 14 L 24 14 C 25.105 14 26 13.105 26 12 L 26 6 C 26 4.895 25.105 4 24 4 L 18 4 z M 9 6 C 10.657 6 12 7.343 12 9 C 12 10.657 10.657 12 9 12 C 7.343 12 6 10.657 6 9 C 6 7.343 7.343 6 9 6 z M 18 6 L 24 6 L 24 12 L 18 12 L 18 6 z M 6 16 C 4.895 16 4 16.895 4 18 L 4 24 C 4 25.105 4.895 26 6 26 L 12 26 C 13.105 26 14 25.105 14 24 L 14 18 C 14 16.895 13.105 16 12 16 L 6 16 z M 18 16 C 16.895 16 16 16.895 16 18 L 16 24 C 16 25.105 16.895 26 18 26 L 24 26 C 25.105 26 26 25.105 26 24 L 26 18 C 26 16.895 25.105 16 24 16 L 18 16 z M 21 17.5 L 24.5 21 L 21 24.5 L 17.5 21 L 21 17.5 z M 9 18 L 11.886719 23 L 6.1132812 23 L 9 18 z" />
    </svg>
  );
}

function ProjectIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="40" height="40" viewBox="0 0 30 30" fill="currentcolor" {...props}>
      <path d="M 14.984375 1.9863281 A 1.0001 1.0001 0 0 0 14 3 L 14 4 L 5 4 L 4 4 A 1.0001 1.0001 0 1 0 3.9804688 6 C 3.9348612 9.0608831 3.6893807 11.887023 3.1523438 14.142578 C 2.5565033 16.645108 1.6039585 18.395538 0.4453125 19.167969 A 1.0001 1.0001 0 0 0 1 21 L 4 21 C 4 22.105 4.895 23 6 23 L 11.787109 23 L 10.148438 26.042969 A 1.5 1.5 0 0 0 9 27.5 A 1.5 1.5 0 0 0 10.5 29 A 1.5 1.5 0 0 0 12 27.5 A 1.5 1.5 0 0 0 11.910156 26.992188 L 14.060547 23 L 15.939453 23 L 18.089844 26.992188 A 1.5 1.5 0 0 0 18 27.5 A 1.5 1.5 0 0 0 19.5 29 A 1.5 1.5 0 0 0 21 27.5 A 1.5 1.5 0 0 0 19.851562 26.042969 L 18.212891 23 L 24 23 C 25.105 23 26 22.105 26 21 L 26 6 A 1.0001 1.0001 0 1 0 26 4 L 25 4 L 16 4 L 16 3 A 1.0001 1.0001 0 0 0 14.984375 1.9863281 z M 5.9589844 6 L 14.832031 6 A 1.0001 1.0001 0 0 0 15.158203 6 L 23.958984 6 C 23.912194 9.0500505 23.687726 11.893974 23.152344 14.142578 C 22.583328 16.532444 21.674397 18.178754 20.585938 19 L 3.1523438 19 C 3.9976592 17.786874 4.6791735 16.365049 5.0976562 14.607422 C 5.6877248 12.129135 5.9137751 9.1554725 5.9589844 6 z" />
    </svg>
  );
}

function PersonIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="40" height="40" viewBox="0 0 30 30" fill="currentcolor" {...props}>
      <path d="M15,3C8.373,3,3,8.373,3,15c0,6.627,5.373,12,12,12s12-5.373,12-12C27,8.373,21.627,3,15,3z M8,22.141 c1.167-3.5,4.667-2.134,5.25-4.03v-1.264c-0.262-0.141-1.013-1.109-1.092-1.865c-0.207-0.018-0.531-0.223-0.627-1.034 c-0.051-0.435,0.153-0.68,0.276-0.757c0,0-0.308-0.702-0.308-1.399C11.5,9.72,12.526,8,15,8c1.336,0,1.75,0.947,1.75,0.947 c1.194,0,1.75,1.309,1.75,2.844c0,0.765-0.308,1.399-0.308,1.399c0.124,0.077,0.328,0.322,0.277,0.757 c-0.096,0.811-0.42,1.016-0.627,1.034c-0.079,0.756-0.829,1.724-1.092,1.865v1.264c0.583,1.897,4.083,0.531,5.25,4.031 c0,0-2.618,2.859-7,2.859C10.593,25,8,22.141,8,22.141z" />
    </svg>
  );
}

Anatomy

Import the component and assemble its parts:

Anatomy

import { Tabs } from '@base-ui-components/react/tabs';

<Tabs.Root>
  <Tabs.List>
    <Tabs.Tab />
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Panel />
</Tabs.Root>

API reference

Root

Groups the tabs and the corresponding panels. Renders a <div> element.

defaultValue

Tabs.Tab.Value

0

Name: defaultValue
Description: The default value. Use when the component is not controlled. When the value is null, no Tab will be selected.
Type: Tabs.Tab.Value
Default: 0

value

Tabs.Tab.Value

—

Name: value
Description: The value of the currently selected Tab. Use when the component is controlled. When the value is null, no Tab will be selected.
Type: Tabs.Tab.Value

onValueChange

function

—

Name: onValueChange
Description: Callback invoked when new value is being set.
Type: | (( value: Tabs.Tab.Value, eventDetails: { reason: 'none' event: ReasonToEvent cancel: () => void allowPropagation: () => void isCanceled: boolean isPropagationAllowed: boolean trigger: HTMLElement | undefined } & { activationDirection: Tabs.Tab.ActivationDirection }, ) => void) | undefined

orientation

Tabs.Root.Orientation

'horizontal'

Name: orientation
Description: The component orientation (layout flow direction).
Type: 'horizontal' | 'vertical' | undefined
Default: 'horizontal'

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Tabs.Root.State) => string)

render

ReactElement | function

—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tabs.Root.State, ) => ReactElement)

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

Indicates the direction of the activation (based on the previous selected tab).

Attribute	Description
`data-orientation`	Indicates the orientation of the tabs.
`data-activation-direction`	Indicates the direction of the activation (based on the previous selected tab).

List

Groups the individual tab buttons. Renders a <div> element.

activateOnFocus

boolean

true

Name: activateOnFocus
Description: Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using Enter or Spacebar key press.
Type: boolean | undefined
Default: true

loop

boolean

true

Name: loop
Description: Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
Type: boolean | undefined
Default: true

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Tabs.List.State) => string)

render

ReactElement | function

—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tabs.List.State, ) => ReactElement)

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

Indicates the direction of the activation (based on the previous selected tab).

Attribute	Description
`data-orientation`	Indicates the orientation of the tabs.
`data-activation-direction`	Indicates the direction of the activation (based on the previous selected tab).

Tab

An individual interactive tab button that toggles the corresponding panel. Renders a <button> element.

value

Tabs.Tab.Value

—

Name: value
Description: The value of the Tab. When not specified, the value is the child position index.
Type: Tabs.Tab.Value

nativeButton

boolean

true

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).
Type: boolean | undefined
Default: true

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Tabs.Tab.State) => string)

render

ReactElement | function

—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tabs.Tab.State, ) => ReactElement)

data-selected

Present when the tab is selected.

data-highlighted

Present when the tab is highlighted.

data-orientation

Indicates the orientation of the tabs.

data-disabled

Present when the tab is disabled.

data-activation-direction

Indicates the direction of the activation (based on the previous selected tab).

Attribute	Description
`data-selected`	Present when the tab is selected.
`data-highlighted`	Present when the tab is highlighted.
`data-orientation`	Indicates the orientation of the tabs.
`data-disabled`	Present when the tab is disabled.
`data-activation-direction`	Indicates the direction of the activation (based on the previous selected tab).

Indicator

A visual indicator that can be styled to match the position of the currently active tab. Renders a <span> element.

renderBeforeHydration

boolean

false

Name: renderBeforeHydration
Description: Whether to render itself before React hydrates. This minimizes the time that the indicator isn’t visible after server-side rendering.
Type: boolean | undefined
Default: false

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Tabs.Indicator.State) => string)

render

ReactElement | function

—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tabs.Indicator.State, ) => ReactElement)

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

Indicates the direction of the activation (based on the previous selected tab).

Attribute	Description
`data-orientation`	Indicates the orientation of the tabs.
`data-activation-direction`	Indicates the direction of the activation (based on the previous selected tab).

--active-tab-bottom

Indicates the distance on the bottom side from the parent's container if the tab is active.

--active-tab-height

Indicates the width of the tab if it is active.

--active-tab-left

Indicates the distance on the left side from the parent's container if the tab is active.

--active-tab-right

Indicates the distance on the right side from the parent's container if the tab is active.

--active-tab-top

Indicates the distance on the top side from the parent's container if the tab is active.

--active-tab-width

Indicates the width of the tab if it is active.

CSS Variable	Description
`--active-tab-bottom`	Indicates the distance on the bottom side from the parent's container if the tab is active.
`--active-tab-height`	Indicates the width of the tab if it is active.
`--active-tab-left`	Indicates the distance on the left side from the parent's container if the tab is active.
`--active-tab-right`	Indicates the distance on the right side from the parent's container if the tab is active.
`--active-tab-top`	Indicates the distance on the top side from the parent's container if the tab is active.
`--active-tab-width`	Indicates the width of the tab if it is active.

Panel

A panel displayed when the corresponding tab is active. Renders a <div> element.

value

Tabs.Tab.Value

—

Name: value
Description: The value of the TabPanel. It will be shown when the Tab with the corresponding value is selected. If not provided, it will fall back to the index of the panel. It is recommended to explicitly provide it, as it's required for the tab panel to be rendered on the server.
Type: Tabs.Tab.Value

className

string | function

—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Tabs.Panel.State) => string)

keepMounted

boolean

false

Name: keepMounted
Description: Whether to keep the HTML element in the DOM while the panel is hidden.
Type: boolean | undefined
Default: false

render

ReactElement | function

—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Tabs.Panel.State, ) => ReactElement)

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

Indicates the direction of the activation (based on the previous selected tab).

data-hidden

Present when the panel is hidden.

data-index

Indicates the index of the tab panel.

Attribute	Description
`data-orientation`	Indicates the orientation of the tabs.
`data-activation-direction`	Indicates the direction of the activation (based on the previous selected tab).
`data-hidden`	Present when the panel is hidden.
`data-index`	Indicates the index of the tab panel.