Skip to content
flyingsalmon

Tabs

Tabs switch between co-equal panels on one page: the tabs own the switch and your app owns the content.

Three days in Lisbon, one plan each morning.

Installation

npx shadcn@latest add @flyingsalmon/tabs

Usage

import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'

export function TabsUsage() {
  return (
    <Tabs defaultValue="itinerary">
      <TabsList>
        <TabsTrigger value="itinerary">Itinerary</TabsTrigger>
        <TabsTrigger value="places">Places</TabsTrigger>
      </TabsList>
      <TabsContent value="itinerary">Three days in Lisbon.</TabsContent>
      <TabsContent value="places">Alfama and Belém.</TabsContent>
    </Tabs>
  )
}

Examples

Automatic activation

The default. Focus the list and use the arrow keys: focus moves and the panel switches at once. That is safe because these panels are local content that does not fetch on mount.

Dates, destination, and travellers for Lisbon long weekend.

Manual activation

Use it when a panel is expensive to mount. Arrow to another tab and a thin bar marks the focused one; press Enter or Space to open it.

Dates, destination, and travellers for Lisbon long weekend.

Disabled tab

A disabled tab dims, takes no pointer events, and is skipped by the arrow keys.

Three days in Lisbon, one plan each morning.

Keeping a panel's state

Type in the note, switch tabs, and come back. forceMount keeps that panel alive across switches; the other panel unmounts as usual.

Guidelines

When to use

  • To switch between two to five views of the same thing, such as a trip’s itinerary, places, and travellers.
  • When the traveller should see one view at a time and move between them without leaving the page.

When not to use

  • Use Sidebar to move between pages. Tabs switch panels in place and do not change the address.
  • Use Toggle group to answer a question or filter a list. A single-mode toggle group is the control for choosing, and it can return to empty.
  • Use Accordion to reveal content under a heading while keeping the others visible, so several sections can be open together.

Do and don’t

  • Do
    Place the tab row directly under the heading of the thing it switches.The tabs read as views of that one thing, and the panel opens right where the reader’s eye leaves the row.
  • Do
    Keep tab labels to one or two words.The tabs sit in one row with no wrapping, so short labels keep every tab in view.
  • Don’t
    Let a switch throw away what the traveller typed.A switch changes the view, not the work. Coming back finds the half-typed note and the scroll position where they were left.
  • Don’t
    Hide a tab whose view is unavailable. Leave it in the row, disabled.A tab that disappears shifts the others. A disabled tab says the view exists but is unavailable.
  • Don’t
    Put tabs inside a tab panel.Two rows of tabs make the traveller track two places at once. Split the content across pages instead.

Accessibility

KeyDescription
TabMoves focus onto the active tab, then into its panel. Disabled tabs are skipped.
ArrowLeftArrowRightMoves focus between tabs. With automatic activation the panel switches too; with manual activation focus moves alone.
HomeEndMoves focus to the first or the last tab.
EnterSpaceOpens the focused tab under manual activation. Under automatic activation the tab is already open.

Tabs draw no focus ring. Their own indicator moves with focus instead: under automatic activation focus and selection coincide, so the moving bar under the active tab is the focus cue, and under manual activation a thin bar marks the focused tab while it differs from the active one. The accessibility page covers the rules every component follows.

API

Tabs

Every other prop passes through to the Radix tabs root. There is no variant, size, or orientation: tabs are underlined, horizontal, and one size matching the default button.

PropTypeDefaultDescription
valuestring–The active tab when the app controls it.
defaultValuestring–The starting tab when the app does not control it.
onValueChange(value: string) => void–Called with the value of the newly active tab.
activationModeTabsActivationModeTabsActivationMode.AutomaticAutomatic opens a tab as focus reaches it. Manual waits for Enter or Space.

TabsTrigger

Also takes the Radix trigger's own props. TabsList and the other parts only take their element's props.

PropTypeDefaultDescription
valuestringRequiredTies the tab to the TabsContent with the same value.
disabledbooleanfalseDims the tab and skips it in the arrow order. Disable a tab rather than removing it, so the others hold their place.

TabsContent

PropTypeDefaultDescription
valuestringRequiredThe tab this panel belongs to.
forceMountbooleanfalseKeeps the panel in the DOM while inactive, hidden from the accessibility tree and the tab order, so its state survives a switch. Use it on a panel that holds typed input or a scroll position.

  • Toggle group

    The control for choosing, where tabs navigate.
  • Accordion

    Sections that open in place and can stay open together.
  • Breadcrumb

    Shows where the traveller is across pages.
  • Motion

    The spring presets behind the sliding indicator.