Skip to main content

Tabs

Swaps between sibling panels without leaving the page.

import { Tabs } from "@/fragments/ui";Source

Preview

<Tabs defaultValue="overview" variant="ghost">
  <Tabs.List>
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
    <Tabs.Tab value="settings">Settings</Tabs.Tab>
  </Tabs.List>

Installation

npx @usefragments/cli add tabs

Writes src/fragments/ui/components/Tabs plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Tabs is a compound: import the root and reach its parts through dot notation.

  • Tabs.List
  • Tabs.Tab
  • Tabs.Panel

A rule tracks the active panel.

<Tabs defaultValue="overview" variant="ghost">
  <Tabs.List>
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
    <Tabs.Tab value="settings">Settings</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="overview">
    <p>Overview content goes here.</p>
  </Tabs.Panel>
  <Tabs.Panel value="analytics">
    <p>Analytics content goes here.</p>
  </Tabs.Panel>
  <Tabs.Panel value="settings">
    <p>Settings content goes here.</p>
  </Tabs.Panel>
</Tabs>

Examples

With Disabled

An unavailable panel stays visible but unreachable.

<Tabs defaultValue="general" variant="ghost">
  <Tabs.List>
    <Tabs.Tab value="general">General</Tabs.Tab>
    <Tabs.Tab value="security">Security</Tabs.Tab>
    <Tabs.Tab value="billing" disabled>Billing</Tabs.Tab>
  </Tabs.List>

List Variant Override

One list can opt out of the root's style.

<Tabs defaultValue="overview" variant="soft">
  <Tabs.List variant="ghost">
    <Tabs.Tab value="overview">Overview</Tabs.Tab>
    <Tabs.Tab value="activity">Activity</Tabs.Tab>
  </Tabs.List>
  <Tabs.Panel value="overview">

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot setTab list and panels (use Tabs.List, Tabs.Tab, Tabs.Panel)
defaultValuestringNot setInitially active tab (uncontrolled)
valuestringNot setControlled active tab value
onValueChangefunctionNot setCalled when active tab changes
orientationenumhorizontalverticalhorizontalTab list orientation
variantenumghostsoftghostDefault chrome for Tabs.List (can be overridden on Tabs.List): ghost draws a rule under the active tab, soft is a filled rail with a selected segment
sizeenumsmmdlgNot setTab control size. Defaults to the component-default control size.

Accessibility

  • Keyboard navigation with arrow keys
  • Tab panels are properly labeled
  • Focus management follows WAI-ARIA tabs pattern

Guidance

Use when

  • Sibling sections of equal weight
  • Cutting scroll on a long page
  • Settings split by category
  • One data set seen several ways

Avoid when

  • Moving between pages (use Sidebar or header navigation)
  • Steps in an order (use Stepper)
  • Content the user compares side by side
  • More options than fit in a row (use Select)
  • SelectalternativeUse Select for many options in compact space
  • MenualternativeUse Menu for action-based navigation

Next steps