Tabs

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

import * as React from 'react';
import { Tabs } from '@base-ui/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/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 active.
Type: Tabs.Tab.Value | undefined
Default: 0

value

Tabs.Tab.Value

—

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

onValueChange

function

—

Name: onValueChange
Description: Callback invoked when new value is being set.
Type: | (( value: Tabs.Tab.Value, eventDetails: Tabs.Root.ChangeEventDetails< 'none', { activationDirection: Tabs.Tab.ActivationDirection; } >, ) => void) | undefined

orientation

Tabs.Root.Orientation

'horizontal'

Name: orientation
Description: The component orientation (layout flow direction).
Type: Tabs.Root.Orientation | 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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Tabs.Root.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

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

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

Additional Types

Tabs.Root.Props

Re-Export of Root props as TabsRootProps

Tabs.Root.State

type TabsRootState = {
  orientation: Tabs.Root.Orientation;
  tabActivationDirection: Tabs.Tab.ActivationDirection;
};

Tabs.Root.ChangeEventReason

type TabsRootChangeEventReason = 'none';

Tabs.Root.ChangeEventDetails

type TabsRootChangeEventDetails = {
  reason: 'none';
  event: Event;
  cancel: () => void;
  allowPropagation: () => void;
  isCanceled: boolean;
  isPropagationAllowed: boolean;
  trigger: Element | undefined;
  activationDirection: Tabs.Tab.ActivationDirection;
};

Tabs.Root.Orientation

type TabsRootOrientation = 'horizontal' | 'vertical';

List

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

activateOnFocus

boolean

false

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

loopFocus

boolean

true

Name: loopFocus
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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Tabs.List.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

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

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

Additional Types

Tabs.List.Props

Re-Export of List props as TabsListProps

Tabs.List.State

type TabsListState = {
  orientation: Tabs.Root.Orientation;
  tabActivationDirection: Tabs.Tab.ActivationDirection;
};

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.
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 (for example, <div>).
Type: boolean | undefined
Default: true

disabled

boolean

—

Name: disabled
Description: Whether the Tab is disabled.

If a first Tab on a <Tabs.List> is disabled, it won’t initially be selected. Instead, the next enabled Tab will be selected. However, it does not work like this during server-side rendering, as it is not known during pre-rendering which Tabs are disabled. To work around it, ensure that defaultValue or value on <Tabs.Root> is set to an enabled Tab’s value.
Type: boolean | undefined

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Tabs.Tab.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

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 active tab).

data-active

Present when the tab is active.

Attribute	Description	-
`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 active tab).
`data-active`	Present when the tab is active.

Additional Types

Tabs.Tab.Props

Re-Export of Tab props as TabsTabProps

Tabs.Tab.State

type TabsTabState = { disabled: boolean; active: boolean; orientation: Tabs.Root.Orientation };

Tabs.Tab.Value

type TabsTabValue = Tabs.Tab.Value;

Tabs.Tab.ActivationDirection

type TabsTabActivationDirection = 'left' | 'right' | 'up' | 'down' | 'none';

Tabs.Tab.Metadata

type TabsTabMetadata = {
  disabled: boolean;
  id: string | undefined;
  value: Tabs.Tab.Value | undefined;
};

Tabs.Tab.Position

type TabsTabPosition = { left: number; right: number; top: number; bottom: number };

Tabs.Tab.Size

type TabsTabSize = { width: number; height: number };

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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Tabs.Indicator.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

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

Attribute	Description	-
`data-orientation`	Indicates the orientation of the tabs.
`data-activation-direction`	Indicates the direction of the activation (based on the previous active 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.

Additional Types

Tabs.Indicator.Props

Re-Export of Indicator props as TabsIndicatorProps

Tabs.Indicator.State

type TabsIndicatorState = {
  activeTabPosition: Tabs.Tab.Position | null;
  activeTabSize: Tabs.Tab.Size | null;
  orientation: Tabs.Root.Orientation;
  tabActivationDirection: Tabs.Tab.ActivationDirection;
};

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 active.
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 | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: Tabs.Panel.State, ) => React.CSSProperties | undefined) | undefined

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) | undefined

data-orientation

Indicates the orientation of the tabs.

data-activation-direction

Indicates the direction of the activation (based on the previous active 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 active tab).
`data-hidden`	Present when the panel is hidden.
`data-index`	Indicates the index of the tab panel.

Additional Types

Tabs.Panel.Props

Re-Export of Panel props as TabsPanelProps

Tabs.Panel.State

type TabsPanelState = {
  hidden: boolean;
  transitionStatus: TransitionStatus;
  orientation: Tabs.Root.Orientation;
  tabActivationDirection: Tabs.Tab.ActivationDirection;
};

Tabs.Panel.Metadata

type TabsPanelMetadata = { id?: string; value: Tabs.Tab.Value };