Headless

Tabs

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

In Nyte

Import

import { Tabs } from "@nyte-ai/ui/tabs";

@nyte-ai/ui/tabs re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

desktop/src/renderer/src/chrome/customize.tsx
desktop/src/renderer/src/chrome/search-palette.tsx
desktop/src/renderer/src/workbench/tab-strip.tsx

The rest of this page is Base UI's documentation for @base-ui/react/tabs, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above.

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

Examples

Animated panels

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.

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>
    {/* @highlight-start */}
    {/* @highlight-text "nativeButton={false}" "render" */}
    <Tabs.Tab nativeButton={false} render={<Link href="/overview" />} value="overview">
      Overview
    </Tabs.Tab>
    {/* @highlight-end */}
  </Tabs.List>
  {/* ... */}
</Tabs.Root>;

API reference

Root

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

Root Props:

Prop	Type	Default	Description
defaultValue	`Tabs.Tab.Value`	`0`	The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active.
value	`Tabs.Tab.Value`	-	The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active.
onValueChange	`((value: Tabs.Tab.Value, eventDetails: Tabs.Root.ChangeEventDetails) => void)`	-	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.
orientation	`Tabs.Root.Orientation`	`'horizontal'`	The component orientation (layout flow direction).
className	`string \| ((state: Tabs.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Tabs.Root.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Tabs.Root.State) => ReactElement)`	-	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.

Root Data Attributes:

Attribute	Type	Description
data-orientation	`'horizontal' \| 'vertical'`	Indicates the orientation of the tabs.
data-activation-direction	`'left' \| 'right' \| 'up' \| 'down' \| 'none'`	Indicates the direction of the activation (based on the previous active tab).

Root.Props

Re-export of Root props.

Root.State

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

Root.ChangeEventReason

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

Root.ChangeEventDetails

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;
};

Root.Orientation

type TabsRootOrientation = 'horizontal' | 'vertical';

List

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

List Props:

Prop	Type	Default	Description
activateOnFocus	`boolean`	`false`	Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using Enter or Space key press.
loopFocus	`boolean`	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
className	`string \| ((state: Tabs.List.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Tabs.List.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Tabs.List.State) => ReactElement)`	-	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.

List Data Attributes:

Attribute	Type	Description
data-orientation	`'horizontal' \| 'vertical'`	Indicates the orientation of the tabs.
data-activation-direction	`'left' \| 'right' \| 'up' \| 'down' \| 'none'`	Indicates the direction of the activation (based on the previous active tab).

List.Props

Re-export of List props.

List.State

type TabsListState = {
  /** 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.

Panel Props:

Prop	Type	Default	Description
value*	`Tabs.Tab.Value`	-	The value of the TabPanel. It will be shown when the Tab with the corresponding value is active.
className	`string \| ((state: Tabs.Panel.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Tabs.Panel.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
keepMounted	`boolean`	`false`	Whether to keep the HTML element in the DOM while the panel is hidden.
render	`ReactElement \| ((props: HTMLProps, state: Tabs.Panel.State) => ReactElement)`	-	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.

Panel Data Attributes:

Attribute	Type	Description
data-orientation	`'horizontal' \| 'vertical'`	Indicates the orientation of the tabs.
data-activation-direction	`'left' \| 'right' \| 'up' \| 'down' \| 'none'`	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.
data-starting-style	-	Present when the panel begins animating in.
data-ending-style	-	Present when the panel is animating out.

Panel.Props

Re-export of Panel props.

Panel.State

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;
};

Panel.Metadata

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

Indicator

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

Indicator Props:

Prop	Type	Default	Description
renderBeforeHydration	`boolean`	`false`	Whether to render itself before React hydrates. This minimizes the time that the indicator isn't visible after server-side rendering.
className	`string \| ((state: Tabs.Indicator.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Tabs.Indicator.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Tabs.Indicator.State) => ReactElement)`	-	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.

Indicator Data Attributes:

Attribute	Type	Description
data-orientation	`'horizontal' \| 'vertical'`	Indicates the orientation of the tabs.
data-activation-direction	`'left' \| 'right' \| 'up' \| 'down' \| 'none'`	Indicates the direction of the activation (based on the previous active tab).

Indicator CSS Variables:

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

Indicator.Props

Re-export of Indicator props.

Indicator.State

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;
};

Tab

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

Tab Props:

Prop	Type	Default	Description
value*	`Tabs.Tab.Value`	-	The value of the Tab.
nativeButton	`boolean`	`true`	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>`).
disabled	`boolean`	-	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.
className	`string \| ((state: Tabs.Tab.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Tabs.Tab.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Tabs.Tab.State) => ReactElement)`	-	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.

Tab Data Attributes:

Attribute	Type	Description
data-orientation	`'horizontal' \| 'vertical'`	Indicates the orientation of the tabs.
data-disabled	-	Present when the tab is disabled.
data-activation-direction	`'left' \| 'right' \| 'up' \| 'down' \| 'none'`	Indicates the direction of the activation (based on the previous active tab).
data-active	-	Present when the tab is active.

Tab.Props

Re-export of Tab props.

Tab.State

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;
};

Tab.Value

type TabsTabValue = Tabs.Tab.Value;

Tab.ActivationDirection

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

Tab.Metadata

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

Tab.Position

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

Tab.Size

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

Export Groups

Tabs.Root: Tabs.Root, Tabs.Root.State, Tabs.Root.Props, Tabs.Root.Orientation, Tabs.Root.ChangeEventReason, Tabs.Root.ChangeEventDetails
Tabs.Tab: Tabs.Tab, Tabs.Tab.Value, Tabs.Tab.ActivationDirection, Tabs.Tab.Position, Tabs.Tab.Size, Tabs.Tab.Metadata, Tabs.Tab.State, Tabs.Tab.Props
Tabs.Indicator: Tabs.Indicator, Tabs.Indicator.State, Tabs.Indicator.Props
Tabs.Panel: Tabs.Panel, Tabs.Panel.Metadata, Tabs.Panel.State, Tabs.Panel.Props
Tabs.List: Tabs.List, Tabs.List.State, Tabs.List.Props
Default: TabsRootOrientation, TabsRootState, TabsRootProps, TabsRootChangeEventReason, TabsRootChangeEventDetails, TabsIndicatorState, TabsIndicatorProps, TabsTabValue, TabsTabActivationDirection, TabsTabPosition, TabsTabSize, TabsTabMetadata, TabsTabState, TabsTabProps, TabsPanelMetadata, TabsPanelState, TabsPanelProps, TabsListState, TabsListProps

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

Tabs.Root.State: TabsRootState
Tabs.Root.Props: TabsRootProps
Tabs.Root.Orientation: TabsRootOrientation
Tabs.Root.ChangeEventReason: TabsRootChangeEventReason
Tabs.Root.ChangeEventDetails: TabsRootChangeEventDetails
Tabs.Tab.Value: TabsTabValue
Tabs.Tab.ActivationDirection: TabsTabActivationDirection
Tabs.Tab.Position: TabsTabPosition
Tabs.Tab.Size: TabsTabSize
Tabs.Tab.Metadata: TabsTabMetadata
Tabs.Tab.State: TabsTabState
Tabs.Tab.Props: TabsTabProps
Tabs.Indicator.State: TabsIndicatorState
Tabs.Indicator.Props: TabsIndicatorProps
Tabs.Panel.Metadata: TabsPanelMetadata
Tabs.Panel.State: TabsPanelState
Tabs.Panel.Props: TabsPanelProps
Tabs.List.State: TabsListState
Tabs.List.Props: TabsListProps