# Tabs

URL: https://ark-ui.com/docs/components/tabs
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/tabs.mdx

Flexible navigation tool with various modes and features.

---

<ComponentPreview id="Tabs" />

## Anatomy

<Anatomy id="tabs" />

```tsx
<Tabs.Root>
  <Tabs.List>
    <Tabs.Trigger />
    <Tabs.Indicator />
  </Tabs.List>
  <Tabs.Content />
</Tabs.Root>
```

## Examples

**Example: basic**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Basic() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Controlled

To create a controlled Tabs component, manage the current selected tab using the `value` prop and update it when the
`onValueChange` event handler is called:

**Example: controlled**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import { track } from 'ripple';
import styles from 'styles/tabs.module.css';

export component Controlled() {
  let value = track<string | null>('account');

  <Tabs.Root
    class={styles.Root}
    {value}
    onValueChange={(e) => {
      @value = e.value;
    }}
  >
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Root Provider

An alternative way to control the tabs is to use the `RootProvider` component and the `useTabs` hook. This way you can
access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Tabs, useTabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component RootProvider() {
  const api = useTabs({ defaultValue: 'account' });

  <div class="stack">
    <output>
      {'selected: '}
      {@api.value}
    </output>
    <Tabs.RootProvider class={styles.Root} value={api}>
      <Tabs.List class={styles.List}>
        <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
        <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
        <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
      </Tabs.List>
      <Tabs.Content class={styles.Content} value="account">
        {'Make changes to your account here.'}
      </Tabs.Content>
      <Tabs.Content class={styles.Content} value="password">
        {'Change your password here.'}
      </Tabs.Content>
      <Tabs.Content class={styles.Content} value="billing">
        {'Manage your billing and payment details.'}
      </Tabs.Content>
    </Tabs.RootProvider>
  </div>
}

```

### Indicator

To provide a visual cue for the selected tab, use the `Tabs.Indicator` component:

**Example: indicator**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Indicator() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.TriggerIndicator} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="billing">{'Billing'}</Tabs.Trigger>
      <Tabs.Indicator class={styles.Indicator} />
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Disabled

To disable a tab, simply pass the `disabled` prop to the `Tabs.Trigger` component:

**Example: disabled-tab**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component DisabledTab() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password" disabled>{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Vertical

The default orientation of the tabs is `horizontal`. To change the orientation, set the `orientation` prop to
`vertical`.

**Example: vertical**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Vertical() {
  <Tabs.Root class={styles.Root} orientation="vertical" defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Lazy Mount

Lazy mounting is a feature that allows the content of a tab to be rendered only when the tab is first activated. This is
useful for performance optimization, especially when tab content is large or complex. To enable lazy mounting, use the
`lazyMount` prop on the `Tabs.Content` component.

In addition, the `unmountOnExit` prop can be used in conjunction with `lazyMount` to unmount the tab content when the
tab is deactivated, freeing up resources. The next time the tab is activated, its content will be re-rendered.

**Example: lazy-mount**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component LazyMount() {
  <Tabs.Root class={styles.Root} lazyMount unmountOnExit defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.TriggerIndicator} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.TriggerIndicator} value="billing">{'Billing'}</Tabs.Trigger>
      <Tabs.Indicator class={styles.Indicator} />
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Manual Activation

By default, the tab can be selected when it receives focus from either the keyboard or pointer interaction. This is
called automatic tab activation.

In contrast, manual tab activation means the tab is selected with the

<kbd>Enter</kbd> key or by clicking on the tab.

**Example: manual-activation**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component ManualActivation() {
  <Tabs.Root class={styles.Root} activationMode="manual" defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">{'Account'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">{'Password'}</Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">{'Billing'}</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

### Links

Use the `asChild` prop to render tab triggers as anchor links. This is useful for SEO and allows tabs to work with
browser navigation.

**Example: links**

```ripple
import { Tabs } from 'ark-ripple/tabs';
import styles from 'styles/tabs.module.css';

export component Links() {
  <Tabs.Root class={styles.Root} defaultValue="account">
    <Tabs.List class={styles.List}>
      <Tabs.Trigger class={styles.Trigger} value="account">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#account' })}>{'Account'}</a>
        }
      </Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="password">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#password' })}>{'Password'}</a>
        }
      </Tabs.Trigger>
      <Tabs.Trigger class={styles.Trigger} value="billing">
        component asChild({ propsFn }) {
          <a {...propsFn({ href: '#billing' })}>{'Billing'}</a>
        }
      </Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content class={styles.Content} value="account">
      {'Make changes to your account here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="password">
      {'Change your password here.'}
    </Tabs.Content>
    <Tabs.Content class={styles.Content} value="billing">
      {'Manage your billing and payment details.'}
    </Tabs.Content>
  </Tabs.Root>
}

```

## Guides

### Router Integration

When using frameworks like Next.js, Remix, or React Router, controlling the active tabs based on the URL can be useful.

To achieve this, you need to do two things:

- Set the `value` prop to the current URL path.
- Listen to the `onValueChange` event and update the URL path.

Here's an example using Remix Router

```tsx
import { Tabs } from '@ark-ui/<framework>/tabs'
import { useLocation, useNavigate, Link } from '@remix-run/react'

export default function App() {
  const { pathname } = useLocation()
  const navigate = useNavigate()
  const lastPathFragment = pathname.substring(pathname.lastIndexOf('/') + 1)
  const activeTab = lastPathFragment.length > 0 ? lastPathFragment : 'homepage'

  return (
    <Tabs.Root
      value={activeTab}
      onValueChange={({ value }) => {
        navigate(`/${value === 'home' ? '' : value}`)
      }}
    >
      <Tabs.List>
        <Tabs.Trigger asChild value="home">
          <Link to="">Home</Link>
        </Tabs.Trigger>
        <Tabs.Trigger asChild value="page-1">
          <Link to="page-1">Page 1</Link>
        </Tabs.Trigger>
        <Tabs.Trigger asChild value="page-2">
          <Link to="page-2">Page 2</Link>
        </Tabs.Trigger>
      </Tabs.List>
    </Tabs.Root>
  )
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `activationMode` | `'manual' | 'automatic'` | No | The activation mode of the tabs. Can be `manual` or `automatic`
- `manual`: Tabs are activated when clicked or press `enter` key.
- `automatic`: Tabs are activated when receiving focus |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `composite` | `boolean` | No | Whether the tab is composite |
| `defaultValue` | `string` | No | The initial selected tab value when rendered.
Use when you don't need to control the selected tab value. |
| `deselectable` | `boolean` | No | Whether the active tab can be deselected when clicking on it. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  root: string
  trigger: (value: string) => string
  list: string
  content: (value: string) => string
  indicator: string
}>` | No | The ids of the elements in the tabs. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loopFocus` | `boolean` | No | Whether the keyboard navigation will loop from last tab to first, and vice versa. |
| `navigate` | `(details: NavigateDetails) => void` | No | Function to navigate to the selected tab when clicking on it.
Useful if tab triggers are anchor elements. |
| `onFocusChange` | `(details: FocusChangeDetails) => void` | No | Callback to be called when the focused tab changes |
| `onValueChange` | `(details: ValueChangeDetails) => void` | No | Callback to be called when the selected/active tab changes |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the tabs. Can be `horizontal` or `vertical`
- `horizontal`: only left and right arrow key navigation will work.
- `vertical`: only up and down arrow key navigation will work. |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |
| `value` | `string` | No | The controlled selected tab value |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | tabs |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the tabs |
| `[data-focus]` | Present when focused |


**TabContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the tab |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabIndicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabList Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**TabTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | The value of the tab |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the tab is disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTabsReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `string` | The current value of the tabs. |
| `focusedValue` | `string` | The value of the tab that is currently focused. |
| `setValue` | `(value: string) => void` | Sets the value of the tabs. |
| `clearValue` | `VoidFunction` | Clears the value of the tabs. |
| `setIndicatorRect` | `(value: string) => void` | Sets the indicator rect to the tab with the given value |
| `syncTabIndex` | `VoidFunction` | Synchronizes the tab index of the content element.
Useful when rendering tabs within a select or combobox |
| `focus` | `VoidFunction` | Set focus on the selected tab trigger |
| `selectNext` | `(fromValue?: string) => void` | Selects the next tab |
| `selectPrev` | `(fromValue?: string) => void` | Selects the previous tab |
| `getTriggerState` | `(props: TriggerProps) => TriggerState` | Returns the state of the trigger with the given props |


## Accessibility

Complies with the [Tabs WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).

### Keyboard Support

<KeyBindingsTable id="tabs" />