Skip to content
Browse documentation
whisk/ui

Tabs

Switch between related views in one context.

Overview

Tabs present closely related views in one context. Each trigger selects one labelled panel without creating a new destination or history entry.

Use when

Readers switch between closely related views without leaving the current context.

Use instead

Use navigation links for destinations that should have their own URL and history entry.

Usage

General settings

Access settings

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@smoothie-framework/whisk-react";

<Tabs defaultValue="general">
  <TabsList aria-label="Settings sections">
    <TabsTrigger value="general">General</TabsTrigger>
    <TabsTrigger value="access">Access</TabsTrigger>
  </TabsList>
  <TabsContent value="general">General settings</TabsContent>
  <TabsContent value="access">Access settings</TabsContent>
</Tabs>

Examples

Keep a fast panel automatic

Automatic activation is the default. Use it when every panel is ready to appear as soon as keyboard focus reaches its tab.

Project summary

Recent project activity

import { Tabs, TabsContent, TabsList, TabsTrigger } from "@smoothie-framework/whisk-react";

<Tabs defaultValue="overview">
  <TabsList aria-label="Project views">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">Project summary</TabsContent>
  <TabsContent value="activity">Recent project activity</TabsContent>
</Tabs>

Require activation for slower panels

Manual activation lets someone move with arrow keys without changing the panel. Use it when loading or rendering a panel may be noticeable. Enter, Space, and click select the focused tab.

Report summary

Detailed report data

<Tabs defaultValue="summary" activationMode="manual">
  <TabsList aria-label="Report views">
    <TabsTrigger value="summary">Summary</TabsTrigger>
    <TabsTrigger value="raw-data">Raw data</TabsTrigger>
  </TabsList>
  <TabsContent value="summary">Report summary</TabsContent>
  <TabsContent value="raw-data">Detailed report data</TabsContent>
</Tabs>

Keep selection in application state

Use controlled Tabs when the active view must follow application state. The callback requests a value; your state update decides the next selection. Do not pass both value and defaultValue.

tsx
type ProjectTabsProps = {
  activeView: string | null;
  onActiveViewChange: (value: string) => void;
};

export function ProjectTabs({ activeView, onActiveViewChange }: ProjectTabsProps) {
  return (
    <Tabs value={activeView} onValueChange={onActiveViewChange}>
      <TabsList aria-label="Project views">
        <TabsTrigger value="overview">Overview</TabsTrigger>
        <TabsTrigger value="activity">Activity</TabsTrigger>
      </TabsList>
      <TabsContent value="overview">Project summary</TabsContent>
      <TabsContent value="activity">Recent project activity</TabsContent>
    </Tabs>
  );
}

Choose a vertical treatment

Vertical Tabs use Up and Down arrow keys. Use this layout when the tab labels need more room or belong beside a persistent panel.

Account settings

Notification settings

<Tabs defaultValue="account" orientation="vertical" variant="outline">
  <TabsList aria-label="Account settings" showSeparator={false}>
    <TabsTrigger value="account">Account</TabsTrigger>
    <TabsTrigger value="notifications">Notifications</TabsTrigger>
  </TabsList>
  <TabsContent value="account">Account settings</TabsContent>
  <TabsContent value="notifications">Notification settings</TabsContent>
</Tabs>

Defer or discard inactive panel children

Tabs always render panel shells so their ARIA relationships remain valid. By default every panel child stays mounted. lazyMount waits until first selection, while unmountOnExit discards inactive panel children and their local state.

tsx
<Tabs defaultValue="overview" lazyMount>
  <TabsList aria-label="Project views">
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="insights">Insights</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">Project summary</TabsContent>
  <TabsContent value="insights">Expensive insights view</TabsContent>
</Tabs>

// Use unmountOnExit instead when inactive panel state should reset.
<Tabs defaultValue="overview" unmountOnExit>{/* parts */}</Tabs>

Props

Component props

PropTypeDefaultDescription
Tabs: value | defaultValuestring | nullnoneControl or initialize selection. Supply exactly one; without either, the first enabled trigger is selected.
Tabs: onValueChange(value: string) => voidnoneReceive a request to select a tab. A controlled parent chooses whether to accept it.
Tabs: activationMode | loopFocusautomatic | manualautomatic | trueSelect on focus or require Enter or Space; wrap arrow-key focus at the list ends by default.
Tabs: orientation | varianthorizontal | vertical; line | subtle | outlinehorizontal | lineSet the layout, matching arrow keys, and visual treatment.
Tabs: lazyMount | unmountOnExitbooleanfalse | falseDefer inactive panel children until first use, or render children only while their panel is active. Panel shells always remain for ARIA relationships.
TabsList: aria-label | aria-labelledbystringnoneRequired accessible name for the tab list.
TabsList: showSeparatorbooleantrueShow the visual separators between inactive tab triggers.
TabsTrigger: value | disabledstring | booleanrequired | falseMatch a non-empty panel value or remove an unavailable view from activation and arrow-key navigation.
TabsContent: value | tabIndexstring | numberrequired | 0Match one trigger and expose its selected panel. Set tabIndex to -1 when the panel starts with a useful focusable element.
className | native propsnative div or button propsnoneApply renderer-native attributes, events, classes, styles, and refs to the relevant part. Whisk/UI owns tab roles, IDs, selection state, and ARIA relationships.

Accessibility

TabsList renders a labelled tablist. Every TabsTrigger renders a button with role=tab, and each TabsContent renders the matching tabpanel. Use unique non-empty values, one trigger and one panel per value, and a visible label for each trigger. Arrow keys move focus, with Left and Right for horizontal lists and Up and Down for vertical lists; Home and End move to the first and last available tab. In automatic mode, focus selects. In manual mode, Enter, Space, or click selects. Disabled, hidden, and inert triggers are skipped. Inactive panels are hidden and inert, and focus returns to the selected trigger if the active panel is hidden while it contains focus.

Content guidance

Use one or two-word, parallel nouns that describe each panel. Do not put instructions or counts in a tab label unless the count is the point of the view.