# Tabs

Switches between related views in the same context.

- Category: Core Elements
- Page: https://wunderui.com/components/tabs
- Tier: Free

## Install

```bash
npx wunderui-cli add tabs
```

## Import

```tsx
import { Tabs, TabBar, TabItem, TabsContent, TabsIndicator, TabsList, TabsTrigger } from "@/components/ui/tabs"
```

## Minimal usage

Then use it:

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Project() {
  return (
    <Tabs defaultValue="overview">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">12 open tasks, 3 due this week.</TabsContent>
      <TabsContent value="activity">Daniel Okafor commented 4 minutes ago.</TabsContent>
    </Tabs>
  )
}
```

Expected result: Two bordered tabs, Overview selected and tinted indigo, with the text 12 open tasks, 3 due this week under them. Click Activity, or arrow to it and press Enter, to swap the text.

## Usage

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="overview" className="w-fit max-w-full">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview" className="text-sm text-text-secondary">12 open tasks, 3 due this week.</TabsContent>
      <TabsContent value="activity" className="text-sm text-text-secondary">Daniel Okafor commented 4 minutes ago.</TabsContent>
      <TabsContent value="settings" className="text-sm text-text-secondary">Two-factor authentication is on.</TabsContent>
    </Tabs>
  )
}
```

## When to use

### Use Tabs for

- Peer views of one object, such as the sections of a project or an account
- A settings page split into a few sections that people switch between
- Views of one list with a count each, such as All, Open and Done

### Use something else

- [Segment](https://wunderui.com/components/segment) for a control that filters a list or sets a chart's period and has no panel of its own
- [Accordion](https://wunderui.com/components/accordion) for several sections that people read in turn and that can be open together
- [Sidebar](https://wunderui.com/components/sidebar) for the pages of the product, where each choice is a route

## Keyboard

The tabs are native buttons with one tab stop. Tab enters the row once and arrow keys move inside it.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the row, onto one tab, and out of it again to the panel. The other tabs are not tab stops. |
| `ArrowRight` or `ArrowLeft` | In a horizontal row: moves focus to the next or previous tab. From the last tab it wraps to the first, and from the first to the last, unless `loopFocus` is off. |
| `ArrowDown` or `ArrowUp` | In a vertical list: moves focus to the next or previous tab, with the same wrapping. Left and Right do nothing there. |
| `Home` or `End` | Moves focus to the first or the last tab. |
| `Enter` or `Space` | Selects the focused tab and shows its panel. A disabled tab can take focus but cannot be selected. |

By default arrow keys only move focus, and Enter or Space selects. Turn on activate on focus to select a tab as soon as it gets focus.

## Behavior

What the tabs do with the selected value, the panels, the looks, overflow and motion.

- **Selected value:** Tabs holds the selected value, which you start with a default or control yourself. Each tab and its panel share one value, a string or number.
- **Panels are not kept:** Only the selected panel is rendered. A hidden panel leaves the DOM, so its text is missing from server HTML and form values inside it are lost unless you keep it mounted.
- **Two looks:** The default look draws every tab as a bordered button, with the selected one tinted indigo. The line look draws bare labels over a 1 px baseline, with a 2 px indigo underline under the selected one.
- **Sizes:** Size sets the height of the row and its tabs: small, medium and large are 32, 36 and 40 px at compact density and 36, 40 and 44 px at comfortable, like Button.
- **Focus:** Keyboard focus shows the shared focus ring on a bordered tab, and inside the label on a line tab. The panel also takes focus, so a long panel scrolls with the keyboard.
- **Overflow:** A row with more tabs than fit scrolls sideways, without a scrollbar, instead of widening the page.
- **Vertical:** In vertical orientation the list stacks beside the panel. Bordered tabs fill the list's width with the label at the start, and the line look draws a rail on the left.
- **Disabled tabs:** A disabled tab can still be reached with arrow keys and is announced as disabled, but it can't be selected. It uses the tertiary text colour and ignores the pointer.
- **Motion:** Switching tabs only fades which tab shows its underline, and the grey baseline never moves. Tab colours fade too, and panels swap without animation.
- **Reduced motion:** With reduced motion the underline appears without the fade. Colour changes stay.

## Anatomy

- `Tabs`: Holds the selected tab and the orientation. It contains the list and the panels: horizontal puts the list above the panel, vertical beside it.
- `TabsList`: The row of tabs, either as bordered buttons (rounded or pill) or as an underline. It comes in three sizes and scrolls sideways when the tabs don't fit.
- `TabsTrigger`: One tab, a button with the tab role. Its value links it to the panel with the same value, and it holds a label, an icon with a label, or a label with a count.
- `Count`: The `count` prop: an indigo light pill after the label, visible on the active tab only.
- `TabsIndicator`: The underline of the selected tab. In the line look each tab draws its own so the grey baseline never moves, and the indicator is a gliding underline for custom layouts.
- `TabsContent`: The panel shown while its tab is selected. It is named by its tab and can take keyboard focus.
- `TabBar`
- `TabItem`

## Best practices

### Do

- Write short labels in sentence case, one or two words: Billing history, not Billing History.
- Keep every tab in a row the same kind: all labels, all icons with labels, or all with counts.
- Always start with a selected tab. Keep the value in state or in the URL when people should be able to come back to a tab.
- Give the list an aria-label, such as Project sections, when a page has more than one row of tabs.
- Keep the number of tabs small enough for a phone. The row scrolls sideways when it runs out of room, and a tab past the edge is easy to miss.

### Don't

- Don't use tabs to move between pages. Links that change the route are navigation with aria-current, not a tab list.
- Don't add your own key handlers to the tabs. Arrow keys, Home and End already move between them, and Tab moves on into the panel.
- Don't set heights on the list or tabs. Pick a size instead, which follows the density and matches the Button sizes.
- Don't hide what people must read or do in a tab they may never open. Put required information outside the tabs.

## API reference

### Tabs

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultValue | TabsTab.Value | 0 | The default value. Use when the component is not controlled. When the value is `null`, no Tab will be active. |
| onValueChange | ((value: TabsTab.Value, eventDetails: TabsRoot.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 `defaultV… |
| orientation | "horizontal" \| "vertical" | "horizontal" | The component orientation (layout flow direction). |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| value | TabsTab.Value |  | The value of the currently active `Tab`. Use when the component is controlled. When the value is `null`, no Tab will be active. |

Also accepts React.HTMLAttributes attributes.

### TabBar

| Prop | Type | Default |
|---|---|---|
| children* | React.ReactNode |  |
| aria-label | string |  |
| className | string |  |

### TabItem

| Prop | Type | Default |
|---|---|---|
| children* | React.ReactNode |  |
| active | boolean |  |
| count | React.ReactNode |  |
| onClick | () => void |  |

Also accepts React.ButtonHTMLAttributes attributes.

### TabsContent

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | TabsTab.Value |  | The value of the TabPanel. It will be shown when the Tab with the corresponding value is active. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| keepMounted | boolean | false | Whether to keep the HTML element in the DOM while the panel is hidden. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### TabsIndicator

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | boolean | false | Whether to render itself before React hydrates. This minimizes the time that the indicator isn't visible after server-side rendering. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### TabsList

| Prop | Type | Default | Description |
|---|---|---|---|
| activateOnFocus | boolean | false | 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 | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| 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. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` (the default) gives the bordered tabs 8 px corners, `pill` rounds them fully. It has no visible effect on the `line` look. |
| size | "lg" \| "sm" \| "md" | "sm" | The height of the row and of its tabs: `sm` (the default), `md` or `lg`, the Button heights. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| variant | "line" \| "default" | "default" | `default` draws every tab as a bordered button. `line` draws bare labels over a baseline, with an underline under the selected one. |

Also accepts React.HTMLAttributes attributes.

### TabsTrigger

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | TabsTab.Value |  | The value of the Tab. |
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| count | number |  | A number after the label, in an indigo pill that is shown on the active tab only. In the `line` variant an inactive tab also draws a grey underline on hover. |
| disabled | boolean |  | 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 know… |
| nativeButton | boolean | true | 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 | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Orientation: tabs above their panel, or beside it

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="general" className="w-fit max-w-full">
      <TabsList>
        <TabsTrigger value="general">General</TabsTrigger>
        <TabsTrigger value="members">Members</TabsTrigger>
        <TabsTrigger value="billing">Billing</TabsTrigger>
      </TabsList>
      <TabsContent value="general" className="text-sm text-text-secondary">Workspace name, address and language.</TabsContent>
      <TabsContent value="members" className="text-sm text-text-secondary">5 members and 2 pending invitations.</TabsContent>
      <TabsContent value="billing" className="text-sm text-text-secondary">Team plan, billed monthly.</TabsContent>
    </Tabs>
  )
}
```

### Content: a label, an icon, or a count

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="overview" className="w-fit max-w-full">
      <TabsList>
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
        <TabsTrigger value="settings">Settings</TabsTrigger>
      </TabsList>
      <TabsContent value="overview" className="text-sm text-text-secondary">12 open tasks, 3 due this week.</TabsContent>
      <TabsContent value="activity" className="text-sm text-text-secondary">Daniel Okafor commented 4 minutes ago.</TabsContent>
      <TabsContent value="settings" className="text-sm text-text-secondary">Two-factor authentication is on.</TabsContent>
    </Tabs>
  )
}
```

### States: default, a disabled tab, and too many tabs

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="general" className="w-fit max-w-full">
      <TabsList>
        <TabsTrigger value="general">General</TabsTrigger>
        <TabsTrigger value="members">Members</TabsTrigger>
        <TabsTrigger value="billing">Billing</TabsTrigger>
      </TabsList>
      <TabsContent value="general" className="text-sm text-text-secondary">Workspace name, address and language.</TabsContent>
      <TabsContent value="members" className="text-sm text-text-secondary">5 members and 2 pending invitations.</TabsContent>
      <TabsContent value="billing" className="text-sm text-text-secondary">Team plan, billed monthly.</TabsContent>
    </Tabs>
  )
}
```

### Count: a pill with the number on the active tab

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@wunderui/react"

export function InboxTabs() {
  return (
    <Tabs defaultValue="all">
      <TabsList variant="line" aria-label="Inbox filters">
        <TabsTrigger value="all" count={128}>All</TabsTrigger>
        <TabsTrigger value="unread" count={12}>Unread</TabsTrigger>
        <TabsTrigger value="mentions" count={5}>Mentions</TabsTrigger>
        <TabsTrigger value="archived" count={214}>Archived</TabsTrigger>
      </TabsList>
      <TabsContent value="all">128 conversations in total.</TabsContent>
      <TabsContent value="unread">12 conversations are waiting for a reply.</TabsContent>
      <TabsContent value="mentions">5 conversations mention you.</TabsContent>
      <TabsContent value="archived">214 conversations are archived.</TabsContent>
    </Tabs>
  )
}
```

## In context

### Account settings: line tabs over three sections

Each section has its own panel of fields. The panels keep one height, so the card does not jump when you switch.

```tsx
import { Button } from "@/components/ui/button"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { Switch } from "@/components/ui/switch"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

export function Example() {
  return (
    <Tabs defaultValue="profile" className="w-full max-w-md">
      <TabsList variant="line" size="md">
        <TabsTrigger value="profile">Profile</TabsTrigger>
        <TabsTrigger value="notifications">Notifications</TabsTrigger>
        <TabsTrigger value="security">Security</TabsTrigger>
      </TabsList>
      <TabsContent value="profile" className="flex min-h-40 flex-col gap-4">
        <div className="flex flex-col gap-2">
          <Label htmlFor="profile-name">Full name</Label>
          <Input id="profile-name" defaultValue="Nora Lindgren" />
        </div>
        <div className="flex flex-col gap-2">
          <Label htmlFor="profile-email">Email address</Label>
          <Input id="profile-email" type="email" defaultValue="info@wunderui.com" />
        </div>
      </TabsContent>
      <TabsContent value="notifications" className="flex min-h-40 flex-col gap-4">
        <div className="flex items-center justify-between gap-4">
          <Label htmlFor="notify-invoices">Email me about new invoices</Label>
          <Switch id="notify-invoices" defaultChecked />
        </div>
        <div className="flex items-center justify-between gap-4">
          <Label htmlFor="notify-mentions">Email me when someone mentions me</Label>
          <Switch id="notify-mentions" />
        </div>
      </TabsContent>
      <TabsContent value="security" className="flex min-h-40 flex-col gap-4">
        <div className="flex items-center justify-between gap-4">
          <Label htmlFor="security-2fa">Two-factor authentication</Label>
          <Switch id="security-2fa" defaultChecked />
        </div>
        <Button variant="plain" className="w-fit">
          Change password
        </Button>
      </TabsContent>
    </Tabs>
  )
}
```

### Task views: tabs with a count

Every tab shows how many tasks it holds, and the count of the open tab turns indigo. The panel lists the matching tasks.

```tsx
import { useState } from "react"
import { Badge } from "@/components/ui/badge"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

const TASKS = [
  { title: "Review the Q3 roadmap", owner: "Nora Lindgren", done: false },
  { title: "Approve invoice INV-1048", owner: "Daniel Okafor", done: false },
  { title: "Update the billing contacts", owner: "Priya Raman", done: false },
  { title: "Publish the brand guidelines", owner: "Tomás Ferreira", done: true },
  { title: "Summarise Tuesday's research", owner: "Maya Kessler", done: false },
  { title: "Migrate the workspace", owner: "Nora Lindgren", done: true },
  { title: "Reset the shared passwords", owner: "Daniel Okafor", done: true },
]

const VIEWS = [
  { value: "all", label: "All", tasks: TASKS },
  { value: "open", label: "Open", tasks: TASKS.filter((task) => !task.done) },
  { value: "done", label: "Done", tasks: TASKS.filter((task) => task.done) },
]

export function Example() {
  const [view, setView] = useState("all")

  return (
    <Tabs value={view} onValueChange={setView} className="w-full max-w-md">
      <TabsList>
        {VIEWS.map((item) => (
          <TabsTrigger key={item.value} value={item.value} className="gap-1.5">
            {item.label}
            <Badge
              color={view === item.value ? "indigo" : "grey"}
              badgeStyle="light"
              shape="pill"
              className="h-5 px-1.5 text-xs"
            >
              {item.tasks.length}
            </Badge>
          </TabsTrigger>
        ))}
      </TabsList>
      {VIEWS.map((item) => (
        <TabsContent key={item.value} value={item.value} className="min-h-64">
          <ul className="flex flex-col divide-y divide-border">
            {item.tasks.map((task) => (
              <li key={task.title} className="flex items-center justify-between gap-4 py-2 text-sm">
                <span className="text-foreground">{task.title}</span>
                <span className="shrink-0 text-text-secondary">{task.owner}</span>
              </li>
            ))}
          </ul>
        </TabsContent>
      ))}
    </Tabs>
  )
}
```

### Workspace settings: vertical line tabs as a side navigation

A vertical list of line tabs sits beside its panel. Use it for a settings page with a few sections that all stay in view.

```tsx
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"

const SECTIONS = [
  { value: "general", label: "General", text: "The name, address and default language of the workspace." },
  { value: "members", label: "Members", text: "5 members and 2 pending invitations. Admins can invite and remove people." },
  { value: "billing", label: "Billing", text: "Team plan, billed monthly. The next invoice is on Dec 1." },
  { value: "keys", label: "API keys", text: "Create keys for scripts and integrations. A key is shown once." },
]

export function Example() {
  return (
    <Tabs defaultValue="general" orientation="vertical" className="w-full max-w-lg">
      <TabsList variant="line">
        {SECTIONS.map((section) => (
          <TabsTrigger key={section.value} value={section.value}>
            {section.label}
          </TabsTrigger>
        ))}
      </TabsList>
      {SECTIONS.map((section) => (
        <TabsContent key={section.value} value={section.value} className="flex flex-col gap-1">
          <h3 className="text-base font-semibold text-foreground">{section.label}</h3>
          <p className="text-sm text-text-secondary">{section.text}</p>
        </TabsContent>
      ))}
    </Tabs>
  )
}
```

## For AI agents

`get_component("tabs")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
