Tabs
⋯
Tabs renders one Base UI root, list, trigger, and panel family. Horizontal and vertical compositions map to the corresponding Figma sets. The mobile view uses the Nesra Select for the same panel values.
Import Tabs from @nesra/ui/tabs or @nesra/ui. Compose one panel for each trigger value and include matching Select items for mobile.
import { Tabs } from "@nesra/ui/tabs";
export function ProjectSections() { return ( <Tabs.Root defaultValue="overview"> <Tabs.List aria-label="Project sections"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="activity">Activity</Tabs.Trigger> </Tabs.List> <Tabs.MobileSelect aria-label="Project sections" items={{ overview: "Overview", activity: "Activity" }} /> <Tabs.Panel value="overview">Project overview</Tabs.Panel> <Tabs.Panel value="activity">Recent activity</Tabs.Panel> </Tabs.Root> );}Composition
Section titled “Composition”Tabs.Root├── Tabs.List│ └── Tabs.Trigger (one per value)├── Tabs.MobileSelect (matching options for mobile)└── Tabs.Panel (one per value)Examples
Section titled “Examples”Basic composition
Section titled “Basic composition”import { Tabs } from "@nesra/ui/tabs";
export function TabsBasicExample() { return ( <Tabs.Root defaultValue="details" className="w-full"> <Tabs.MobileSelect aria-label="Settings section" items={{ details: "My details", profile: "Profile", notifications: "Notifications" }} /> <Tabs.List aria-label="Settings sections"> <Tabs.Trigger value="details">My details</Tabs.Trigger> <Tabs.Trigger value="profile">Profile</Tabs.Trigger> <Tabs.Trigger value="notifications" badge={<span aria-label="2 new">2</span>}> Notifications </Tabs.Trigger> </Tabs.List> <div className="pt-nesra-padding-2xl"> <Tabs.Panel value="details">Edit your details here.</Tabs.Panel> <Tabs.Panel value="profile">Review your profile here.</Tabs.Panel> <Tabs.Panel value="notifications">Manage your notifications here.</Tabs.Panel> </div> </Tabs.Root> );}Variants and disabled
Section titled “Variants and disabled”The six visual variants are shown with a disabled trigger.
import { Select } from "@nesra/ui/select";import { Tabs, type TabsVariant } from "@nesra/ui/tabs";
const variants: TabsVariant[] = ["brand", "gray", "line", "border", "minimal", "pill"];
export function TabsVariantsExample() { return ( <div className="grid w-full gap-nesra-spacing-lg md:grid-cols-2"> {variants.map((variant) => ( <div key={variant} className="min-w-0 rounded-nesra-md border border-nesra-stroke-divider p-nesra-padding-lg" > <p className="mb-nesra-spacing-sm type-nesra-body-small-semibold">{variant}</p> <Tabs.Root defaultValue="overview" variant={variant} className="w-full"> <Tabs.MobileSelect aria-label={`${variant} section`} items={{ overview: "Overview", activity: "Activity", unavailable: "Unavailable" }} > <Select.Option value="overview">Overview</Select.Option> <Select.Option value="activity">Activity</Select.Option> <Select.Option value="unavailable" disabled> Unavailable </Select.Option> </Tabs.MobileSelect> <Tabs.List aria-label={`${variant} tabs`}> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="activity">Activity</Tabs.Trigger> <Tabs.Trigger value="unavailable" disabled> Unavailable </Tabs.Trigger> </Tabs.List> <Tabs.Panel value="overview" className="pt-nesra-padding-lg"> Overview panel </Tabs.Panel> <Tabs.Panel value="activity" className="pt-nesra-padding-lg"> Activity panel </Tabs.Panel> <Tabs.Panel value="unavailable" className="pt-nesra-padding-lg"> Unavailable panel </Tabs.Panel> </Tabs.Root> </div> ))} </div> );}sm and md follow the trigger heights listed below. The mobile Select is 36px and 40px tall, respectively.
import { Tabs } from "@nesra/ui/tabs";
export function TabsSizesExample() { return ( <div className="grid w-full gap-nesra-spacing-lg"> {(["sm", "md"] as const).map((size) => ( <div key={size}> <p className="mb-nesra-spacing-xs type-nesra-body-small-medium">{size}</p> <Tabs.Root defaultValue="overview" size={size}> <Tabs.MobileSelect aria-label={`${size} report section`} items={{ overview: "Overview", activity: "Activity" }} /> <Tabs.List aria-label={`${size} report sections`}> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="activity">Activity</Tabs.Trigger> </Tabs.List> <Tabs.Panel value="overview">Overview report</Tabs.Panel> <Tabs.Panel value="activity">Activity report</Tabs.Panel> </Tabs.Root> </div> ))} </div> );}Vertical
Section titled “Vertical”import { Tabs } from "@nesra/ui/tabs";
export function TabsVerticalExample() { return ( <Tabs.Root defaultValue="account" orientation="vertical" variant="line" size="md" className="w-full" > <Tabs.MobileSelect aria-label="Account section" items={{ account: "Account", security: "Security" }} /> <div className="sm:flex sm:gap-nesra-spacing-lg"> <Tabs.List aria-label="Account sections"> <Tabs.Trigger value="account">Account</Tabs.Trigger> <Tabs.Trigger value="security">Security</Tabs.Trigger> </Tabs.List> <div className="min-w-0 pt-nesra-padding-lg sm:pt-0"> <Tabs.Panel value="account">Account settings</Tabs.Panel> <Tabs.Panel value="security">Security settings</Tabs.Panel> </div> </div> </Tabs.Root> );}Full width
Section titled “Full width”fullWidth divides available horizontal list width between triggers. It does not apply to vertical tabs.
import { Tabs } from "@nesra/ui/tabs";
export function TabsFullWidthExample() { return ( <Tabs.Root defaultValue="overview" variant="pill" fullWidth size="md" className="w-full"> <Tabs.MobileSelect aria-label="Report section" items={{ overview: "Overview", activity: "Activity" }} /> <Tabs.List aria-label="Report sections"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="activity">Activity</Tabs.Trigger> </Tabs.List> <Tabs.Panel value="overview">Overview report</Tabs.Panel> <Tabs.Panel value="activity">Activity report</Tabs.Panel> </Tabs.Root> );}Controlled selection
Section titled “Controlled selection”Use value and onValueChange when application state owns the active section.
import { Tabs } from "@nesra/ui/tabs";import { useState } from "react";
export function TabsControlledExample() { const [active, setActive] = useState("overview");
return ( <Tabs.Root value={active} onValueChange={(next) => { if (typeof next === "string") setActive(next); }} className="w-full" > <Tabs.MobileSelect aria-label="Report section" items={{ overview: "Overview", activity: "Activity" }} /> <Tabs.List aria-label="Report sections"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="activity">Activity</Tabs.Trigger> </Tabs.List> <p className="pt-nesra-padding-lg">Current section: {active}</p> <Tabs.Panel value="overview">Overview report</Tabs.Panel> <Tabs.Panel value="activity">Activity report</Tabs.Panel> </Tabs.Root> );}Long labels and overflow
Section titled “Long labels and overflow”The desktop list scrolls horizontally within its available width. Each label stays on one line.
import { Tabs } from "@nesra/ui/tabs";
const sections = [ { value: "overview", label: "Overview" }, { value: "activity", label: "Recent activity" }, { value: "notifications", label: "Notifications and preferences" }, { value: "billing", label: "Billing" }, { value: "integrations", label: "Integrations" },];const sectionItems = Object.fromEntries(sections.map(({ value, label }) => [value, label]));
export function TabsOverflowExample() { return ( <Tabs.Root defaultValue="overview" variant="line" className="w-80 max-w-full"> <Tabs.MobileSelect aria-label="Settings section" items={sectionItems} /> <Tabs.List aria-label="Settings sections"> {sections.map((section) => ( <Tabs.Trigger key={section.value} value={section.value}> {section.label} </Tabs.Trigger> ))} </Tabs.List> {sections.map((section) => ( <Tabs.Panel key={section.value} value={section.value} className="pt-nesra-padding-lg"> {section.label} panel </Tabs.Panel> ))} </Tabs.Root> );}Responsive behavior
Section titled “Responsive behavior”Below 640px, Tabs.List is hidden and Tabs.MobileSelect appears. It renders the Nesra Select with a 36px height for sm and 40px for md. Its items must use the same string values as the triggers and panels. Use custom Select.Option children when an option must be disabled, and also provide the matching items map so the selected label renders. The Select needs an accessible name such as aria-label.
At 640px and wider, horizontal lists stay on one line and scroll horizontally if necessary. Labels remain intact. A vertical list retains its column layout. Badge content is a consumer slot. It does not depend on a public Badge component.
Desktop trigger heights follow the Figma visual type:
| Variant | Horizontal sm / md |
Vertical sm / md |
|---|---|---|
brand, gray, minimal |
36px / 44px | 36px / 44px |
line |
32px / 36px | 24px / 32px |
border |
36px / 44px | 36px / 44px |
pill |
32px / 36px | 32px / 36px |
The border list adds padding and a border around those triggers. Its total height is 44px for sm and 56px for md. The pill list is 38px and 42px tall.
pill labels are Body/Small or Body/Medium Medium, with 14px and 16px side padding and a 4px icon
gap. The other types use Semibold. A horizontal line trigger keeps its label at the top with 4px
side padding, a 4px (sm) or 6px (md) icon gap, and 12px between triggers. A vertical line
trigger has 12px (sm) or 14px (md) side padding and 8px between triggers.
Light and Dark
Section titled “Light and Dark”Every trigger color comes from a semantic role, so the same classes render both modes when an
ancestor sets .dark or data-theme="dark".
| State | Roles |
|---|---|
| Inactive | text-support on alpha-transparent |
| Hover | brand: action-secondary-hover and text-secondary. gray and pill: foundation-bg-gray. border: foundation-bg-neutral with shadow-xs. line: stroke-brand-primary underline |
| Selected | text-body on the indicator: foundation-bg-brand-primary-50 (brand), foundation-bg-gray (gray), foundation-bg-neutral (border, minimal), stroke-brand-primary (line) |
Selected pill |
text-on-brand on action-primary-default. The label is white in Light and gray-950 in Dark |
| Keyboard focus | Two layers: a 2px foundation-bg-neutral gap and a 4px effects-focus-ring ring. brand, gray, border, and panels use shadow-nesra-focus-ring-offset outside the trigger. line, minimal, and pill draw an inset 2px effects-focus-ring ring with a 2px foundation-bg-neutral gap inside it, because their scrolling list leaves no room outside the trigger |
| Disabled | text-disabled |
The selected line label uses text-body. The Figma canvas binds text-brand-primary, which has
the same value as the inactive text-support label. Figma draws every focus ring outside the trigger.
Tabs are still unpublished in Figma.
Accessibility
Section titled “Accessibility”Base UI associates each trigger and panel by their shared value, manages roving focus, and sets selected and hidden states. Tabs.Panel keeps inactive content mounted and hidden. Tabs.List uses manual activation by default. Arrow keys move focus. Enter or Space activates the focused tab. Set activateOnFocus on the list for automatic activation. Use an accessible list name, and keep the mobile Select items aligned with enabled triggers.
The desktop selection indicator moves to the active trigger unless the user prefers reduced motion. Panel content switches immediately.
API reference
Section titled “API reference”Tabs.Root
Section titled “Tabs.Root”| Prop | Type | Default | Effect |
|---|---|---|---|
value |
string |
— | Selects the tab in a controlled root. |
defaultValue |
string |
First enabled | Sets the initial uncontrolled selection. |
orientation |
"horizontal" | "vertical" |
"horizontal" |
Sets list and keyboard direction. |
variant |
"brand" | "gray" | "line" | "border" | "minimal" | "pill" |
"brand" |
Selects the visual type. |
size |
"sm" | "md" |
"sm" |
Sets trigger and mobile selector size. |
fullWidth |
boolean |
false |
Divides horizontal list width among tabs. |
onValueChange receives the selected value and Base UI event details. An automatic fallback can
send null when no enabled trigger remains. The mobile select then shows no selection. Tabs.Root also accepts Base UI Tabs root props,
className, and a ref to the root element.
The API variant names map to Figma as follows:
| API variant | Horizontal Figma type | Vertical Figma type |
|---|---|---|
brand |
Button brand | Button primary |
gray |
Button gray | Button gray |
line |
Underline | Line |
border |
Button border | Button border |
minimal |
Button minimal | Button minimal |
pill |
Pill | Pill |
Tabs.List
Section titled “Tabs.List”| Prop | Type | Default | Effect |
|---|---|---|---|
activateOnFocus |
boolean |
false |
Activates a tab when arrow navigation focuses it. |
loopFocus |
boolean |
true |
Wraps arrow navigation from the last tab to the first. |
Tabs.List also accepts Base UI Tabs list props, className, and a ref to the list element.
Tabs.Trigger
Section titled “Tabs.Trigger”| Prop | Type | Default | Effect |
|---|---|---|---|
value |
string |
— | Required. Associates the trigger with a panel. |
disabled |
boolean |
false |
Skips keyboard focus and prevents selection. |
badge |
ReactNode |
— | Renders content after the label. |
Tabs.Trigger also accepts Base UI Tabs tab props, className, and a ref to the button element.
Tabs.Panel
Section titled “Tabs.Panel”The required string value associates the panel with a trigger. Inactive panels always remain
mounted and hidden, so keepMounted is not configurable. Tabs.Panel accepts the other Base UI
Tabs panel props, className, and a ref to the panel element.
Tabs.MobileSelect
Section titled “Tabs.MobileSelect”Accepts Nesra Select props, className, and a ref to the trigger button. Its value follows the root’s selection, so value, defaultValue, and onValueChange cannot be set on the mobile selector. Provide an items map for standard options or custom Select.Option children for disabled options. Selecting an option activates the matching enabled trigger.
Visual values use the color roles, typography roles, layout scale, and shape tokens.