# @fayegram-ai/faye-ui/navigation/tabs

Public exports and dependency-resolved component properties, with usage and rendering guidance.

## Import

```tsx
import { Tabs } from '@fayegram-ai/faye-ui/navigation/tabs';
```

[Usage and behavior guide](/docs/navigation/) · [API JSON](/api/packages/navigation/tabs.json)

This entry declares a client boundary. Follow the rendering guide for framework integration.

## Public exports

| Name | Kind | Resolved declaration type |
|---|---|---|
| `ScrollableTabsListProps` | type | `ScrollableTabsListProps` |
| `Tabs` | value | `{ readonly Root: { (input: Omit<import("@base-ui/react").TabsRootProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined; }): import("react").ReactElement; displayName: string; }; readonly List: { (input: Omit<import("@base-ui/react").TabsListProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs"… (full type in API JSON)` |

## Tabs

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Tabs.Root

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: TabsRootState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `defaultValue` | No | `any` | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
| `onValueChange` | No | `((value: TabsTab.Value, eventDetails: TabsRoot.ChangeEventDetails) => void) \| undefined` | 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` | No | `Orientation \| undefined` | The component orientation (layout flow direction). |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsRootState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: TabsRootState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `value` | No | `any` | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Tabs.List

| Property | Required | Type | Meaning |
|---|---|---|---|
| `activateOnFocus` | No | `boolean \| undefined` | Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press. |
| `className` | No | `string \| ((state: TabsListState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `loopFocus` | No | `boolean \| undefined` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsListState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: TabsListState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Tabs.ScrollableList

| Property | Required | Type | Meaning |
|---|---|---|---|
| `activateOnFocus` | No | `boolean \| undefined` | Whether to automatically change the active tab on arrow key focus. Otherwise, tabs will be activated using <kbd>Enter</kbd> or <kbd>Space</kbd> key press. |
| `className` | No | `string \| ((state: TabsListState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `containerClassName` | No | `string \| undefined` | See the usage contract and declaration. |
| `loopFocus` | No | `boolean \| undefined` | Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys. |
| `nextLabel` | No | `string \| undefined` | See the usage contract and declaration. |
| `previousLabel` | No | `string \| undefined` | See the usage contract and declaration. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsListState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: TabsListState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Tabs.Tab

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: TabsTabState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `disabled` | No | `boolean \| undefined` | 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. |
| `nativeButton` | No | `boolean \| undefined` | 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>`). |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsTabState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: TabsTabState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `value` | Yes | `any` | The value of the Tab. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Tabs.Panel

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: TabsPanelState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `keepMounted` | No | `boolean \| undefined` | Whether to keep the HTML element in the DOM while the panel is hidden. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsPanelState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: TabsPanelState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `value` | Yes | `any` | The value of the TabPanel. It will be shown when the Tab with the corresponding value is active. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Tabs.Indicator

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: TabsIndicatorState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TabsIndicatorState> \| undefined` | 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. |
| `renderBeforeHydration` | No | `boolean \| undefined` | Whether to render itself before React hydrates. This minimizes the time that the indicator isn't visible after server-side rendering. |
| `style` | No | `CSSProperties \| ((state: TabsIndicatorState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"tabs", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

## Defaults and customization

Descriptor defaults: `{"size":"md","tone":"neutral"}`. Parts: `root`, `list`, `tab`, `panel`, `indicator`, `scrollable-list`, `scroll-button`. Explicit instance props take precedence over configured defaults.

Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.

## State, events and accessibility

For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.

## Declaration authority

Generated from `packages/faye-ui/dist/navigation/tabs.d.ts` after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. [React DOM attributes](https://react.dev/reference/react-dom/components/common) and [Base UI component contracts](https://base-ui.com/react/overview/quick-start) describe the inherited foundations.