> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tabs Component: Switchable Panels and Tab Navigation

> Use Tabs, TabsList, TabsTab, and TabsPanel to organize related content into switchable panels with full keyboard navigation and ARIA tab semantics.

The `Tabs`, `TabsList`, `TabsTab`, and `TabsPanel` components let you divide related content into labelled sections the user can switch between without leaving the page. They are **Status: Draft** and are backed by [Mantine's Tabs](https://mantine.dev/core/tabs/) primitive. Clementine exports all four sub-components from `@clementine-ds/ui` with the Clementine theme applied.

***

## When to use

* You have **two or more sibling views** of related content that share the same page region (e.g., Overview / Activity / Settings within a details panel).
* The content in each view is conceptually parallel — all tabs are peers, not steps.
* You want to keep all content accessible without navigating to a new route.

## When not to use

* **Top-level or site-wide navigation** — use a sidebar or nav bar so users always know where they are in the overall app.
* **Step-by-step workflows** — use a `Stepper` that enforces order and shows progress.
* **Primary actions** — use `Button` components; tabs select content, they don't trigger actions.
* **Only one panel of content** — a single tab adds visual noise without benefit.

***

## Usage

Import `Tabs`, `TabsList`, `TabsTab`, and `TabsPanel` from `@clementine-ds/ui`. Compose them together: `TabsList` holds all `TabsTab` buttons; each `TabsPanel` is paired with a `TabsTab` via matching `value` strings.

### Uncontrolled

```tsx theme={null}
import { Tabs, TabsList, TabsTab, TabsPanel } from '@clementine-ds/ui';

export function ProjectTabs() {
  return (
    <Tabs defaultValue="overview">
      <TabsList>
        <TabsTab value="overview">Overview</TabsTab>
        <TabsTab value="activity">Activity</TabsTab>
        <TabsTab value="settings">Settings</TabsTab>
      </TabsList>

      <TabsPanel value="overview" pt="md">
        Overview content goes here.
      </TabsPanel>

      <TabsPanel value="activity" pt="md">
        Activity feed goes here.
      </TabsPanel>

      <TabsPanel value="settings" pt="md">
        Settings form goes here.
      </TabsPanel>
    </Tabs>
  );
}
```

### Controlled

```tsx theme={null}
import { useState } from 'react';
import { Tabs, TabsList, TabsTab, TabsPanel } from '@clementine-ds/ui';

export function ControlledTabs() {
  const [activeTab, setActiveTab] = useState<string | null>('overview');

  return (
    <Tabs value={activeTab} onChange={setActiveTab}>
      <TabsList>
        <TabsTab value="overview">Overview</TabsTab>
        <TabsTab value="activity">Activity</TabsTab>
        <TabsTab value="settings">Settings</TabsTab>
      </TabsList>

      <TabsPanel value="overview" pt="md">
        Overview content goes here.
      </TabsPanel>

      <TabsPanel value="activity" pt="md">
        Activity feed goes here.
      </TabsPanel>

      <TabsPanel value="settings" pt="md">
        Settings form goes here.
      </TabsPanel>
    </Tabs>
  );
}
```

### With a disabled tab

Set `disabled` on any `TabsTab` to make it non-interactive. Disabled tabs are skipped during arrow-key navigation.

```tsx theme={null}
import { Tabs, TabsList, TabsTab, TabsPanel } from '@clementine-ds/ui';

export function TabsWithDisabled() {
  return (
    <Tabs defaultValue="overview">
      <TabsList>
        <TabsTab value="overview">Overview</TabsTab>
        <TabsTab value="billing" disabled>Billing</TabsTab>
        <TabsTab value="settings">Settings</TabsTab>
      </TabsList>

      <TabsPanel value="overview" pt="md">Overview content.</TabsPanel>
      <TabsPanel value="billing" pt="md">Billing content.</TabsPanel>
      <TabsPanel value="settings" pt="md">Settings content.</TabsPanel>
    </Tabs>
  );
}
```

### Vertical orientation

```tsx theme={null}
import { Tabs, TabsList, TabsTab, TabsPanel } from '@clementine-ds/ui';

export function VerticalTabs() {
  return (
    <Tabs defaultValue="overview" orientation="vertical">
      <TabsList>
        <TabsTab value="overview">Overview</TabsTab>
        <TabsTab value="activity">Activity</TabsTab>
        <TabsTab value="settings">Settings</TabsTab>
      </TabsList>

      <TabsPanel value="overview" pl="md">Overview content.</TabsPanel>
      <TabsPanel value="activity" pl="md">Activity content.</TabsPanel>
      <TabsPanel value="settings" pl="md">Settings content.</TabsPanel>
    </Tabs>
  );
}
```

***

## Props

### `Tabs`

`TabsProps` extends Mantine's `TabsProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | — | `TabsList` and `TabsPanel` elements. |
| `value` | `string \| null` | — | Controlled active tab value. |
| `defaultValue` | `string \| null` | — | Initial active tab value (uncontrolled). |
| `onChange` | `(value: string \| null) => void` | — | Called when the active tab changes. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction of the tab list. |
| `placement` | `"left" \| "right"` | `"left"` | `TabsList` placement relative to panels; applies only when `orientation="vertical"`. |
| `color` | `MantineColor` | — | Default color for all tabs (overridden per-tab with `TabsTab`'s `color` prop). |
| `radius` | `MantineRadius \| number` | — | Border-radius of tab buttons. |
| `inverted` | `boolean` | — | When set, places the active indicator on the opposite side of the tab list border. |
| `keepMounted` | `boolean` | `true` | When `false`, unmounts inactive `TabsPanel` content instead of hiding it. |
| `keepMountedMode` | `"activity" \| "display-none"` | — | Controls how inactive panels are hidden when `keepMounted` is `true`. |
| `activateTabWithKeyboard` | `boolean` | `true` | When `false`, arrow keys move focus but do not activate the tab automatically. |
| `allowTabDeactivation` | `boolean` | — | When set, clicking the active tab deselects it. |
| `loop` | `boolean` | — | When set, arrow key navigation wraps from last tab back to first (and vice versa). |
| `autoContrast` | `boolean` | — | Adjusts text color based on background for the `pills` variant. |
| `id` | `string` | auto-generated | Base id used to generate `aria-controls` and `aria-labelledby` pairings. |

### `TabsList`

`TabsListProps` extends Mantine's `TabsListProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `React.ReactNode` | **required** | `TabsTab` components. |
| `grow` | `boolean` | — | When set, all tabs expand equally to fill available width. |
| `justify` | `JustifyContent` | — | CSS `justify-content` value for aligning tabs within the list. |

### `TabsTab`

`TabsTabProps` extends Mantine's `TabsTabProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `value` | `string` | **required** | Identifier that links this tab to its corresponding `TabsPanel`. |
| `children` | `React.ReactNode` | — | Tab label text or content. |
| `disabled` | `boolean` | — | Prevents the tab from being activated via mouse or keyboard. |
| `color` | `MantineColor` | — | Overrides the `Tabs`-level color for this individual tab. |
| `leftSection` | `React.ReactNode` | — | Content (e.g., an icon) rendered to the left of the label. |
| `rightSection` | `React.ReactNode` | — | Content (e.g., a badge) rendered to the right of the label. |

### `TabsPanel`

`TabsPanelProps` extends Mantine's `TabsPanelProps`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `value` | `string` | **required** | Identifier matching the `TabsTab` that reveals this panel. |
| `children` | `React.ReactNode` | **required** | Panel content. |
| `keepMounted` | `boolean` | — | Overrides the parent `Tabs`'s `keepMounted` for this individual panel. |

***

## Interaction states

| State | Description |
| - | - |
| `default` | Tab is visible but not active and not focused. |
| `hover` | Cursor moves over a tab button. |
| `focus` | Keyboard focus ring appears on a tab button (`:focus-visible`). |
| `selected` | The active tab; `aria-selected="true"` is set and the indicator is shown. |
| `disabled` | Tab is visible but greyed out; pointer events and keyboard activation are suppressed; tab is skipped during arrow-key navigation. |

***

## Keyboard interactions

| Key | Condition | Behaviour |
| - | - | - |
| `ArrowRight` | `orientation="horizontal"` | Focuses (and activates) the next enabled tab. |
| `ArrowLeft` | `orientation="horizontal"` | Focuses (and activates) the previous enabled tab. |
| `ArrowDown` | `orientation="vertical"` | Focuses (and activates) the next enabled tab. |
| `ArrowUp` | `orientation="vertical"` | Focuses (and activates) the previous enabled tab. |
| `Home` | — | Focuses (and activates) the first enabled tab. |
| `End` | — | Focuses (and activates) the last enabled tab. |
| `Tab` | — | Moves focus from the tab list into the active panel's content. |

Set `activateTabWithKeyboard={false}` on `Tabs` if you want arrow keys to move focus without activating tabs automatically (useful when panels contain async-loaded content).

***

## Accessibility

* `TabsList` renders `role="tablist"`. Each `TabsTab` renders `role="tab"`. Each `TabsPanel` renders `role="tabpanel"`.
* `aria-selected` is set to `"true"` on the active tab and `"false"` on all others.
* `aria-controls` on each `TabsTab` points to its associated `TabsPanel` id. `aria-labelledby` on each `TabsPanel` points back to its `TabsTab`.
* Add `aria-label` to `TabsList` to give the group of tabs an accessible name that screen readers announce when focus first enters the list.
* If you use icon-only tabs with no visible text, add `aria-label` to each `TabsTab` so screen readers can announce the tab's purpose.

```tsx theme={null}
// ✅ Icon-only tab — accessible via aria-label
<TabsTab value="settings" aria-label="Settings" leftSection={<GearIcon size={16} />} />

// ✅ Named tab list
<TabsList aria-label="Project sections">
  ...
</TabsList>
```

***

> [!WARNING]
>
> **Draft status.** The `Tabs` components are currently **Draft**. Arrow-key navigation between tabs needs verification in your target browsers before shipping to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.