---
title: "Tabs"
description: "A row of tabs that switches between panels sharing one region. The list is one tab stop with a roving focus, and choosing a tab swaps the panel."
url: "https://opsinjs.pensievelabs.org/docs/components/tabs"
source: "https://opsinjs.pensievelabs.org/docs/components/tabs.md"
section: "Components"
status: "shipped"
kind: "component"
category: "navigation"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["tab list", "view switcher"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="tabs"
  status="shipped"
  questions="[
  &#x22;No contrast pair has been measured: the active tab against the row, the tab-list rail, or the indicator bar against its ground.&#x22;,
  &#x22;Nobody has listened to this control in a screen reader, so the roving focus and the panel association are untested.&#x22;,
  &#x22;Forced colours and prefers-contrast: more are unhandled, so whether the selection survives the platform's own pair has not been tested.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="tabs" unbuilt="false" importPath="@/components/ui/tabs" dependencies="[&#x22;@base-ui/react&#x22;]" />

```tsx
import { Tabs } from "@/components/ui/tabs"
```

```tsx
<Tabs
  label="Reading detail"
  value={panel}
  onValueChange={setPanel}
  items={[
    { value: "overview", label: "Overview", panel: <Overview /> },
    { value: "history", label: "History", panel: <History /> },
    { value: "notes", label: "Notes", panel: <Notes /> },
  ]}
/>
```

## Examples [#examples]

<ComponentPreview name="tabs" />

### Switching between panels [#switching-between-panels]

Three panels share one region, from `items`. Choosing a tab swaps the whole
panel, not one setting of a view.

<ComponentPreview name="tabs-switching-panels" kind="example" align="start" />

### Tabs in a card [#tabs-in-a-card]

The card header names the subject and `items` fills its body, so a tab swaps the
body without the card moving.

<ComponentPreview name="tabs-in-a-card" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Two or three distinct panels share one region and only one is worth showing at a time.&#x22;,
  &#x22;Folding secondary views of one subject, such as an overview, a history and notes, behind their own tabs.&#x22;,
  &#x22;Views a reader moves between often and expects to find in a familiar bar.&#x22;,
]"
  avoid="[
  { case: &#x22;The choice sets one parameter of a view that stays on the surface, such as a chart's week window.&#x22;, instead: &#x22;segmented-control&#x22; },
  { case: &#x22;The choice is a small set of exclusive options taken as a form input, submitted as a value.&#x22;, instead: &#x22;radio-group&#x22; },
  { case: &#x22;The panels are steps in a sequence, where progress and a next action matter most.&#x22;, instead: &#x22;stepper&#x22; },
]"
/>

## Accessibility [#accessibility]

Base UI's Tabs carries the tested WAI-ARIA pattern and the wrapper overrides none of
it. Activation is manual, three sighted carriers plus `aria-selected` mark the active
tab, and the row draws neutral chrome with no status or category axis. The indicator
glides to the chosen tab on `spring-snap`, and under `prefers-reduced-motion` it moves in
one frame. Rendered, it
shows no axe violation, target-size breach, focus gap or 320px reflow, and the audit
changed nothing.

**Residual items.**

* Each tab floors its height at `--opsin-target-minimum` with padding but sets no
  `min-w`, the house treatment for a word-labelled target under SC 2.5.8.
* The `label` prop applies only as the tablist's `aria-label`, which is right here
  because every tab shows its own text.
* Contrast pairs for the active ink, the rail and the indicator stay unmeasured.

<KeyboardTable
  name="tabs"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Moves focus into the tab list, onto the active tab&#x22;,
    notes: &#x22;One tab stop for the list. The active panel is the next stop.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Moves focus back out of the tab list&#x22;,
    notes: &#x22;One stop in reverse too, so focus leaves the row.&#x22;,
  },
  {
    keys: &#x22;Arrow Right, Arrow Down&#x22;,
    action: &#x22;Moves the highlight to the next tab&#x22;,
    notes: &#x22;No panel swap. Wraps around, skips disabled tabs, mirrored under right-to-left.&#x22;,
  },
  {
    keys: &#x22;Arrow Left, Arrow Up&#x22;,
    action: &#x22;Moves the highlight to the previous tab&#x22;,
    notes: &#x22;Wraps to the last tab, skips disabled tabs, swaps no panel.&#x22;,
  },
  {
    keys: &#x22;Home, End&#x22;,
    action: &#x22;Moves the highlight to the first or last tab&#x22;,
    notes: &#x22;Both skip disabled tabs and neither swaps the panel.&#x22;,
  },
  {
    keys: &#x22;Enter, Space&#x22;,
    action: &#x22;Activates the highlighted tab and shows its panel&#x22;,
    notes: &#x22;The commit step of manual activation.&#x22;,
  },
]"
/>

<ContrastReport component="tabs" />

## Props interface [#props-interface]

<PropsTable name="TabsProps" />

`value` and `onValueChange` make this controlled, with no internal selection
state. A `value` matching no item renders no active tab and warns in
development. `items` holds each tab's value, label and panel together.
