Skip to content
WunderUI

Tabs

Free

Switch between related views of one object, such as the sections of a project or an account.

npx wunderui-cli add tabs

Playground

12 open tasks, 3 due this week.

Installation

bash
npx wunderui-cli add tabs

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Segment for a control that filters a list or sets a chart's period and has no panel of its own
  • Accordion for several sections that people read in turn and that can be open together
  • Sidebar for the pages of the product, where each choice is a route

Orientation

Horizontal tabs sit above their panel. Vertical tabs stack beside it as a side navigation, and Up and Down move between them.

Workspace name, address and language.

Content

A tab holds a label, an icon with a label, or a label with a count. Keep every tab in a row the same kind.

12 open tasks, 3 due this week.

States

Point at a tab or press Tab and the arrow keys to see hover, pressed and focus. A disabled tab can be reached with the arrow keys and is announced as disabled, but it cannot be selected.

Workspace name, address and language.

Count

count on a TabsTrigger adds an indigo pill after the label, shown on the active tab only. In the line variant an inactive tab also draws a grey underline on hover, like the active tab's indigo one. It replaces TabBar and TabItem.

128 conversations in total.

Keyboard interactions

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

TaborShiftTab
Moves focus into the row, onto one tab, and out of it again to the panel. The other tabs are not tab stops.
ArrowRightorArrowLeft
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 is off.
ArrowDownorArrowUp
In a vertical list: moves focus to the next or previous tab, with the same wrapping. Left and Right do nothing there.
HomeorEnd
Moves focus to the first or the last tab.
EnterorSpace
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 and motion

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

The parts the component is made of. Each one renders a you can target from CSS.

Two-factor is on.
  • data-slot="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.

  • data-slot="tabs-list"

    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.

  • data-slot="tabs-trigger"

    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.

  • data-slot="tabs-trigger-count"Optional

    The prop: an indigo light pill after the label, visible on the active tab only.

  • data-slot="tabs-indicator"Optional

    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.

  • data-slot="tabs-content"

    The panel shown while its tab is selected. It is named by its tab and can take keyboard focus.

  • data-slot="tab-bar"Optional
  • data-slot="tab-item"Optional

Best practices

  • Do

    Write short labels in sentence case, one or two words: Billing history, not Billing History.

  • Do

    Keep every tab in a row the same kind: all labels, all icons with labels, or all with counts.

  • Do

    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.

  • Do

    Give the list an aria-label, such as Project sections, when a page has more than one row of tabs.

  • Do

    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

    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

    Don't set heights on the list or tabs. Pick a size instead, which follows the density and matches the Button sizes.

  • Don’t

    Don't hide what people must read or do in a tab they may never open. Put required information outside the tabs.

API reference

One table per part, in the order of the anatomy. Every part also takes the props of the Base UI part it wraps (such as , and ) and the native attributes of its element.

Holds the selected tab and the orientation. It contains the list and the panels: horizontal puts the list above the panel, vertical beside it.

PropTypeDefaultDescription
valueTabsTab.Value—The value of the currently active . Use when the component is controlled. When the value is , no Tab will be active.
defaultValueTabsTab.Value0The default value. Use when the component is not controlled. When the value is , no Tab will be active.
onValueChange(value, eventDetails) => void—Callback invoked when new value is being set. The event is for user-initiated changes, such as a click or keyboard navigation; for the first automatic selection or fallback in uncontrolled roots when `defaultV…
orientation"horizontal" | "vertical""horizontal"The component orientation (layout flow direction).

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.

PropTypeDefaultDescription
variant"line" | "default""default" draws every tab as a bordered button. draws bare labels over a baseline, with an underline under the selected one.
shape"rounded" | "pill""rounded" (the default) gives the bordered tabs 8 px corners, rounds them fully. It has no visible effect on the look.
size"lg" | "sm" | "md""sm"The height of the row and of its tabs: (the default), or , the Button heights.
activateOnFocusbooleanfalseWhether 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.
loopFocusbooleantrueWhether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.

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.

PropTypeDefaultDescription
value requiredTabsTab.Value—The value of the Tab.
disabledboolean—Whether the Tab is disabled. If a first Tab on a 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…
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
countnumber—A number after the label, in an indigo pill that is shown on the active tab only. In the variant an inactive tab also draws a grey underline on hover.

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.

PropTypeDefaultDescription
renderBeforeHydrationbooleanfalseWhether to render itself before React hydrates. This minimizes the time that the indicator isn't visible after server-side rendering.

The panel shown while its tab is selected. It is named by its tab and can take keyboard focus.

PropTypeDefaultDescription
value requiredTabsTab.Value—The value of the TabPanel. It will be shown when the Tab with the corresponding value is active.
keepMountedbooleanfalseWhether to keep the HTML element in the DOM while the panel is hidden.

PropTypeDefaultDescription
children requiredReactNode—
aria-labelstring—

PropTypeDefaultDescription
children requiredReactNode—
activeboolean—
countReactNode—
onClick() => void—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("tabs")
Installnpx wunderui-cli add tabs

The full library index for assistants is at /llms.txt.