Tabs

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

Workspace stats and activity.

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

export default function ExampleTabs() {
  return (
    <Tabs.Root className={styles.Root} 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>
      <div className={styles.PanelViewport}>
        <Tabs.Panel className={styles.Panel} value="overview">
          <p className={styles.Paragraph}>Workspace stats and activity.</p>
        </Tabs.Panel>
        <Tabs.Panel className={styles.Panel} value="projects">
          <p className={styles.Paragraph}>Milestones and deadlines.</p>
        </Tabs.Panel>
        <Tabs.Panel className={styles.Panel} value="account">
          <p className={styles.Paragraph}>Profile and preferences.</p>
        </Tabs.Panel>
      </div>
    </Tabs.Root>
  );
}

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>

Animate panels as they activate using the data-starting-style and data-ending-style attributes. The data-activation-direction attribute indicates which direction the newly active tab is relative to the previously active one, letting panels slide in from the correct side.

Workspace stats and activity.

index.tsx index.module.css

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

export default function ExampleAnimatedTabs() {
  return (
    <Tabs.Root className={styles.Root} 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>
      <div className={styles.PanelViewport}>
        <Tabs.Panel className={styles.Panel} value="overview">
          <p className={styles.Paragraph}>Workspace stats and activity.</p>
        </Tabs.Panel>
        <Tabs.Panel className={styles.Panel} value="projects">
          <p className={styles.Paragraph}>Milestones and deadlines.</p>
        </Tabs.Panel>
        <Tabs.Panel className={styles.Panel} value="account">
          <p className={styles.Paragraph}>Profile and preferences.</p>
        </Tabs.Panel>
      </div>
    </Tabs.Root>
  );
}

Links

Use the render prop and set nativeButton={false} on <Tabs.Tab> to render tabs as anchor elements.

Tabs as links

import { Tabs } from '@base-ui/react/tabs';
import Link from 'next/link';

<Tabs.Root>
  <Tabs.List>
    <Tabs.Tab nativeButton={false} render={<Link href="/overview" />} value="overview">
      Overview
    </Tabs.Tab>
  </Tabs.List>
  {/* ... */}
</Tabs.Root>

API reference

Root

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

defaultValueTabs.Tab.Value0

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

valueTabs.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

onValueChangefunction—

Name: onValueChange
Description: Callback invoked when new value is being set.

The event reason is 'none' for user-initiated changes, such as a click or keyboard navigation; 'initial' for the first automatic selection or fallback in uncontrolled roots when defaultValue is omitted or undefined, including when the implicit initial value is disabled or missing; 'disabled' for automatic fallback when the selected tab becomes disabled in uncontrolled roots; or 'missing' for automatic fallback when the selected tab is removed, or when an explicit defaultValue never matches a mounted tab in uncontrolled roots.

For automatic changes, the selected value can be null when no enabled Tab is available as a fallback.

Automatic changes cannot be canceled; calling eventDetails.cancel() for 'initial', 'disabled', or 'missing' has no effect.
Type: | (( value: Tabs.Tab.Value, eventDetails: Tabs.Root.ChangeEventDetails, ) => void) | undefined

orientationTabs.Root.Orientation'horizontal'

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

classNamestring | 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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Tabs.Root.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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

Tabs.Root.PropsHide

Re-Export of Root props as TabsRootProps

Tabs.Root.StateHide

type TabsRootState = {
  /** The component orientation. */
  orientation: Tabs.Root.Orientation;
  /** The direction used for tab activation. */
  tabActivationDirection: Tabs.Tab.ActivationDirection;
}

Tabs.Root.ChangeEventReasonHide

type TabsRootChangeEventReason = 'none' | 'disabled' | 'missing' | 'initial'

Tabs.Root.ChangeEventDetailsHide

type TabsRootChangeEventDetails = (
  | { reason: 'none' }
  | { reason: 'disabled' }
  | { reason: 'missing' }
  | { reason: 'initial' }
) & {
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  activationDirection: Tabs.Tab.ActivationDirection;
}

Tabs.Root.OrientationHide

type TabsRootOrientation = 'horizontal' | 'vertical'

List

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

activateOnFocusbooleanfalse

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

loopFocusbooleantrue

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

classNamestring | 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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Tabs.List.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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

Tabs.List.PropsHide

Re-Export of List props as TabsListProps

Tabs.List.StateHide

type TabsListState = {
  /** The component orientation. */
  orientation: Tabs.Root.Orientation;
  /** The direction used for tab activation. */
  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

nativeButtonbooleantrue

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

disabledboolean—

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

classNamestring | 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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Tabs.Tab.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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

Tabs.Tab.PropsHide

Re-Export of Tab props as TabsTabProps

Tabs.Tab.StateHide

type TabsTabState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the component is active. */
  active: boolean;
  /** The component orientation. */
  orientation: Tabs.Root.Orientation;
  /** The direction used for tab activation. */
  tabActivationDirection: Tabs.Tab.ActivationDirection;
}

Tabs.Tab.ValueHide

type TabsTabValue = Tabs.Tab.Value

Tabs.Tab.ActivationDirectionHide

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

Tabs.Tab.MetadataHide

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

Tabs.Tab.PositionHide

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

Tabs.Tab.SizeHide

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.

renderBeforeHydrationbooleanfalse

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

classNamestring | 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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Tabs.Indicator.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | 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

Tabs.Indicator.PropsHide

Re-Export of Indicator props as TabsIndicatorProps

Tabs.Indicator.StateHide

type TabsIndicatorState = {
  /** The active tab position. */
  activeTabPosition: Tabs.Tab.Position | null;
  /** The active tab size. */
  activeTabSize: Tabs.Tab.Size | null;
  /** The component orientation. */
  orientation: Tabs.Root.Orientation;
  /** The direction used for tab activation. */
  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

classNamestring | 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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Tabs.Panel.State, ) => React.CSSProperties | undefined) | undefined

keepMountedbooleanfalse

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

renderReactElement | 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

Tabs.Panel.PropsHide

Re-Export of Panel props as TabsPanelProps

Tabs.Panel.StateHide

type TabsPanelState = {
  /** Whether the component is hidden. */
  hidden: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** The component orientation. */
  orientation: Tabs.Root.Orientation;
  /** The direction used for tab activation. */
  tabActivationDirection: Tabs.Tab.ActivationDirection;
}

Tabs.Panel.MetadataHide

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

Tabs

Anatomy

Examples

Animated panels

Links

API reference

Root

Tabs.Root.PropsHide

Tabs.Root.StateHide

Tabs.Root.ChangeEventReasonHide

Tabs.Root.ChangeEventDetailsHide

Tabs.Root.OrientationHide

List

Tabs.List.PropsHide

Tabs.List.StateHide

Tab

Tabs.Tab.PropsHide

Tabs.Tab.StateHide

Tabs.Tab.ValueHide

Tabs.Tab.ActivationDirectionHide

Tabs.Tab.MetadataHide

Tabs.Tab.PositionHide

Tabs.Tab.SizeHide

Indicator

Tabs.Indicator.PropsHide

Tabs.Indicator.StateHide

Panel

Tabs.Panel.PropsHide

Tabs.Panel.StateHide

Tabs.Panel.MetadataHide