# Tabs (/cloud/headless/tabs)



{/* Generated by scripts/sync-base-ui-reference.mjs. Edit the script, not this file. */}

## In Nyte [#in-nyte]

```ts title="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 [#anatomy]

Import the component and assemble its parts:

```jsx title="Anatomy"
import { Tabs } from '@base-ui/react/tabs';

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

## Examples [#examples]

### Animated panels [#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 [#links]

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

```jsx title="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 [#api-reference]

### Root [#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.&#xA;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.&#xA;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&#xA;or keyboard navigation; `'initial'` for the first automatic selection or&#xA;fallback in uncontrolled roots when `defaultValue` is omitted or&#xA;`undefined`, including when the implicit initial value is disabled or&#xA;missing; `'disabled'` for automatic fallback when the selected tab becomes&#xA;disabled in uncontrolled roots; or `'missing'` for automatic fallback when&#xA;the selected tab is removed, or when an explicit `defaultValue` never&#xA;matches a mounted tab in uncontrolled roots. For automatic changes, the selected value can be `null` when no enabled Tab&#xA;is available as a fallback. Automatic changes cannot be canceled; calling `eventDetails.cancel()` for&#xA;`'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&#xA;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&#xA;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&#xA;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 [#rootprops]

Re-export of [Root](#root) props.

### Root.State [#rootstate]

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

### Root.ChangeEventReason [#rootchangeeventreason]

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

### Root.ChangeEventDetails [#rootchangeeventdetails]

```typescript
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 [#rootorientation]

```typescript
type TabsRootOrientation = 'horizontal' | 'vertical';
```

### List [#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.&#xA;Otherwise, tabs will be activated using Enter or Space key press.                                                      |
| loopFocus       | `boolean`                                                                               | `true`  | Whether to loop keyboard focus back to the first item&#xA;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&#xA;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&#xA;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&#xA;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 [#listprops]

Re-export of [List](#list) props.

### List.State [#liststate]

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

### Panel [#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&#xA;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&#xA;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&#xA;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 [#panelprops]

Re-export of [Panel](#panel) props.

### Panel.State [#panelstate]

```typescript
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 [#panelmetadata]

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

### Indicator [#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.&#xA;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&#xA;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&#xA;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&#xA;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 [#indicatorprops]

Re-export of [Indicator](#indicator) props.

### Indicator.State [#indicatorstate]

```typescript
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 [#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&#xA;via the `render` prop.&#xA;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.&#xA;Instead, the next enabled Tab will be selected.&#xA;However, it does not work like this during server-side rendering, as it is not known&#xA;during pre-rendering which Tabs are disabled.&#xA;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&#xA;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&#xA;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&#xA;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 [#tabprops]

Re-export of [Tab](#tab) props.

### Tab.State [#tabstate]

```typescript
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 [#tabvalue]

```typescript
type TabsTabValue = Tabs.Tab.Value;
```

### Tab.ActivationDirection [#tabactivationdirection]

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

### Tab.Metadata [#tabmetadata]

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

### Tab.Position [#tabposition]

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

### Tab.Size [#tabsize]

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

## Export Groups [#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 [#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`