---
title: Tabs
subtitle: A component for toggling between related panels on the same page.
description: A high-quality, unstyled React tabs component for toggling between related panels on the same page.
---
> FineSoft Components documentation. Independent Stencil port; not the official Base UI website.
>
> React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable.
# Tabs
A high-quality, unstyled React tabs component for toggling between related panels on the same page.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* docs-comparison.tsx */
import ReactTabs from './react-tabs';
import StencilTabs from './stencil-tabs';
import { StencilComparison } from 'docs/src/components/StencilComparison';
export default function ExampleTabs() {
return } stencil={} />;
}
```
```tsx
/* react-tabs.tsx */
import { Tabs } from '@base-ui/react/tabs';
const tabClassName =
'flex h-[calc(2rem+1px)] items-center justify-center bg-transparent px-2 py-0 font-inherit text-sm font-normal leading-5 break-keep whitespace-nowrap text-neutral-600 outline-none select-none hover:text-neutral-950 focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white data-active:text-neutral-950 dark:text-neutral-300 dark:hover:text-white dark:data-active:text-white';
const panelClassName =
'col-start-1 row-start-1 flex w-full items-center justify-center bg-white p-4 text-center text-sm text-neutral-950 outline-none focus-visible:z-1 focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-neutral-950 dark:focus-visible:outline-white dark:bg-neutral-950 dark:text-white [[hidden]]:hidden';
export default function ExampleTabs() {
return (
Overview
Projects
Account
);
}
```
```css
/* stencil.css */
/* Example layout and visual exceptions. Default component styles come from the theme. */
@layer fs-theme {
.demo-tabs-hero-panel-viewport {
box-sizing: border-box;
display: grid;
grid-template-columns: minmax(0, 1fr);
width: 100%;
min-height: 8rem;
border-inline: var(--fs-border-width) solid var(--fs-color-foreground);
border-block: var(--fs-border-width) solid var(--fs-color-foreground);
}
.demo-tabs-hero-paragraph {
margin: 0;
}
}
```
## Stencil boundary
The Stencil family retains Light DOM. Root and List own layout and tablist semantics;
Tab keeps its native control in the same tree as the List and Panel so that focus,
`aria-controls`, `aria-labelledby`, and native form associations remain intact.
Panel owns physical mounting and transitions, while Indicator owns measured positioning.
No additional ShadowRoot or CSS part is introduced.
The Base UI theme is built in; select `data-fs-theme="base-ui"`
on an ancestor to enable the optional theme. Existing CSS variables and Light DOM
selectors remain available; host and native control styles are not isolated.
## Anatomy
Import the component and assemble its parts:
```jsx title="Anatomy"
import { Tabs } from '@base-ui/react/tabs';
;
```
## 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.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* docs-comparison.tsx */
import ReactTabs from './react-tabs';
import StencilTabs from './stencil-tabs';
import { StencilComparison } from 'docs/src/components/StencilComparison';
export default function ExampleTabs() {
return } stencil={} />;
}
```
```tsx
/* react-tabs.tsx */
import { Tabs } from '@base-ui/react/tabs';
export default function ExampleAnimatedTabs() {
return (
Overview
Projects
Account
);
}
```
```css
/* stencil.css */
/* Example layout and visual exceptions. Default component styles come from the theme. */
@layer fs-theme {
.demo-tabs-animated-panels-panel-viewport {
box-sizing: border-box;
position: relative;
display: grid;
grid-template-columns: minmax(0, 1fr);
width: 100%;
min-height: 8rem;
overflow: hidden;
border-inline: var(--fs-border-width) solid var(--fs-color-foreground);
border-block: var(--fs-border-width) solid var(--fs-color-foreground);
background-color: var(--fs-color-surface);
}
.demo-tabs-animated-panels-paragraph {
margin: 0;
}
}
```
### Links
Use the `render` prop and set `nativeButton={false}` on `` to render tabs as anchor elements.
```jsx title="Tabs as links"
import { Tabs } from '@base-ui/react/tabs';
import Link from 'next/link';
{/* @highlight-start */}
{/* @highlight-text "nativeButton={false}" "render" */}
} value="overview">
Overview
{/* @highlight-end */}
{/* ... */}
;
```
## API reference
### Root
Groups the tabs and the corresponding panels.
Renders a `
` 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](/react/components/tabs.md) props.
### Root.State
```typescript
type TabsRootState = {
/** The component orientation. */
orientation: Tabs.Root.Orientation;
/** The direction used for tab activation. */
tabActivationDirection: Tabs.Tab.ActivationDirection;
};
```
### Root.ChangeEventReason
```typescript
type TabsRootChangeEventReason = 'none' | 'disabled' | 'missing' | 'initial';
```
### Root.ChangeEventDetails
```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
```typescript
type TabsRootOrientation = 'horizontal' | 'vertical';
```
### List
Groups the individual tab buttons.
Renders a `
` 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](/react/components/tabs.md) props.
### List.State
```typescript
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 `
` 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](/react/components/tabs.md) props.
### Panel.State
```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
```typescript
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 `` 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](/react/components/tabs.md) props.
### Indicator.State
```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
An individual interactive tab button that toggles the corresponding panel.
Renders a `