Components
Tabs
Switch between related views inside the same page region.
Tabs switches between related panels without navigating away. Use underline tabs for regular
content navigation, pills for compact view switching, and enclosed tabs for settings or segmented
panels.
The component is built on Base UI Tabs. Base UI owns selection state, roving focus, keyboard navigation, and tab-to-panel relationships; Orkest UI owns the visual design and public API.
Import the components from @orkest/ui/client.
Basic usage#
import { Stack, Text } from '@orkest/ui';
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Tabs defaultValue="overview">
<TabsList>
<TabsTrigger value="overview">Overview</TabsTrigger>
<TabsTrigger value="activity">Activity</TabsTrigger>
<TabsTrigger value="settings">Settings</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="overview">
<Text size="sm" tone="muted">
A summary of the project, recent changes, and open work.
</Text>
</TabsContent>
<TabsContent value="activity">
<Text size="sm" tone="muted">
Commits, reviews, and comments from the last seven days.
</Text>
</TabsContent>
<TabsContent value="settings">
<Text size="sm" tone="muted">
Visibility, members, and notification preferences.
</Text>
</TabsContent>
</Tabs>
);
}Anatomy#
Tabsowns the selected value and connects tabs to their panels.TabsListis the tab strip. It also controls keyboard behavior throughactivationModeandloop.TabsTriggeris one tab. Thevalueprop must match the correspondingTabsContent.TabsContentis the panel for a value. Only the active panel is rendered by default.TabsIndicatoris an optional moving highlight. Place it insideTabsList, after the triggers.
String values keep state stable when tabs are added, removed, or reordered. Avoid array indexes.
Variants#
underline is the default and fits regular content navigation.
pills uses a filled active tab and works well for compact view switching.
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Tabs defaultValue="day">
<TabsList variant="pills">
<TabsTrigger value="day">Day</TabsTrigger>
<TabsTrigger value="week">Week</TabsTrigger>
<TabsTrigger value="month">Month</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="day">Today's activity.</TabsContent>
<TabsContent value="week">This week's activity.</TabsContent>
<TabsContent value="month">This month's activity.</TabsContent>
</Tabs>
);
}enclosed places the tabs in a sunken segmented container, which suits settings and layout
switchers.
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Tabs defaultValue="list">
<TabsList variant="enclosed">
<TabsTrigger value="list">List</TabsTrigger>
<TabsTrigger value="board">Board</TabsTrigger>
<TabsTrigger value="timeline">Timeline</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="list">Tasks grouped in a list.</TabsContent>
<TabsContent value="board">Tasks grouped by status.</TabsContent>
<TabsContent value="timeline">Tasks ordered by date.</TabsContent>
</Tabs>
);
}Vertical tabs#
Set orientation="vertical" on Tabs. The root lays the list beside the active panel by default,
and the arrow keys switch to ArrowUp and ArrowDown.
import { Stack, Text } from '@orkest/ui';
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
import { Bell, Settings, User } from 'lucide-react';
export function Example() {
return (
<Tabs defaultValue="profile" orientation="vertical">
<TabsList variant="pills">
<TabsTrigger value="profile" icon={User}>
Profile
</TabsTrigger>
<TabsTrigger value="notifications" icon={Bell} badge={2}>
Notifications
</TabsTrigger>
<TabsTrigger value="preferences" icon={Settings}>
Preferences
</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="profile">
<Text size="sm" tone="muted">Name, avatar, and contact details.</Text>
</TabsContent>
<TabsContent value="notifications">
<Text size="sm" tone="muted">Two unread notifications.</Text>
</TabsContent>
<TabsContent value="preferences">
<Text size="sm" tone="muted">Language, time zone, and keyboard shortcuts.</Text>
</TabsContent>
</Tabs>
);
}Sizes and full width#
size accepts sm, md, and lg. fullWidth stretches a horizontal list and divides its width
evenly between the tabs.
import { Stack } from '@orkest/ui';
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Stack gap={5}>
<Tabs defaultValue="first">
<TabsList size="sm" variant="pills">
<TabsTrigger value="first">Small</TabsTrigger>
<TabsTrigger value="second">Tabs</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="first">Small size.</TabsContent>
<TabsContent value="second">Small size.</TabsContent>
</Tabs>
<Tabs defaultValue="first">
<TabsList size="md" variant="pills">
<TabsTrigger value="first">Medium</TabsTrigger>
<TabsTrigger value="second">Tabs</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="first">Medium size.</TabsContent>
<TabsContent value="second">Medium size.</TabsContent>
</Tabs>
<Tabs defaultValue="first">
<TabsList size="lg" variant="pills">
<TabsTrigger value="first">Large</TabsTrigger>
<TabsTrigger value="second">Tabs</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="first">Large size.</TabsContent>
<TabsContent value="second">Large size.</TabsContent>
</Tabs>
</Stack>
);
}import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Tabs defaultValue="all">
<TabsList fullWidth variant="pills">
<TabsTrigger value="all">All</TabsTrigger>
<TabsTrigger value="active">Active</TabsTrigger>
<TabsTrigger value="archived">Archived</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="all">All projects.</TabsContent>
<TabsContent value="active">Active projects.</TabsContent>
<TabsContent value="archived">Archived projects.</TabsContent>
</Tabs>
);
}Activation mode#
activationMode controls what happens when an arrow key moves focus.
automatic(default) activates the focused tab immediately. Use it when panels are already available.manualmoves focus only and waits for Enter or Space. Use it when switching triggers expensive work such as a network request.
import { Stack, Text } from '@orkest/ui';
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
return (
<Tabs defaultValue="details">
<TabsList activationMode="manual">
<TabsTrigger value="details">Details</TabsTrigger>
<TabsTrigger value="members">Members</TabsTrigger>
<TabsTrigger value="history">History</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="details">
<Text size="sm" tone="muted">
Arrow keys move focus. Press Enter or Space to load a panel.
</Text>
</TabsContent>
<TabsContent value="members">
<Text size="sm" tone="muted">
Members load only after you confirm the selection.
</Text>
</TabsContent>
<TabsContent value="history">
<Text size="sm" tone="muted">
History keeps the current panel until you activate it.
</Text>
</TabsContent>
</Tabs>
);
}Controlled state#
import { useState } from 'react';
import { Stack, Text } from '@orkest/ui';
import {
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
const [value, setValue] = useState('overview');
return (
<Stack gap={2}>
<Tabs value={value} onValueChange={setValue}>
<TabsList>
<TabsTrigger value="overview">Overview</TabsTrigger>
<TabsTrigger value="activity">Activity</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="overview">Overview panel.</TabsContent>
<TabsContent value="activity">Activity panel.</TabsContent>
</Tabs>
<Text size="sm" tone="muted">Active tab: {value}</Text>
</Stack>
);
}Disabled tabs#
Disable a single tab with TabsTrigger disabled. Disable the whole list with Tabs disabled; the
active panel stays visible but the list no longer accepts pointer or keyboard interaction.
Disabled tabs are skipped by arrow-key navigation, Home, and End.
import { useState } from 'react';
import { Stack } from '@orkest/ui';
import {
Switch,
Tabs,
TabsContent,
TabsIndicator,
TabsList,
TabsTrigger,
} from '@orkest/ui/client';
export function Example() {
const [disabled, setDisabled] = useState(false);
return (
<Stack gap={3}>
<Switch
label="Disable the whole tab list"
checked={disabled}
onCheckedChange={setDisabled}
/>
<Tabs defaultValue="general" disabled={disabled}>
<TabsList>
<TabsTrigger value="general">General</TabsTrigger>
<TabsTrigger value="billing" disabled>
Billing
</TabsTrigger>
<TabsTrigger value="advanced">Advanced</TabsTrigger>
<TabsIndicator />
</TabsList>
<TabsContent value="general">General settings.</TabsContent>
<TabsContent value="billing">Billing settings.</TabsContent>
<TabsContent value="advanced">Advanced settings.</TabsContent>
</Tabs>
</Stack>
);
}Keyboard interaction#
| Key | Behavior |
|---|---|
| ArrowLeft / ArrowRight | Move focus between horizontal tabs |
| ArrowUp / ArrowDown | Move focus between vertical tabs |
| Home / End | Move to the first or last enabled tab |
| Enter / Space | Activate the focused tab in manual mode |
| Tab | Move into or out of the tab list |
Focus wraps at the ends by default. Set loop={false} on TabsList to stop at the last tab.
Disabled tabs are skipped.
Accessibility#
TabsListrendersrole="tablist"and exposes the orientation to assistive technology.- Each
TabsTriggerrendersrole="tab"witharia-selected, and is linked to its panel througharia-controls. - Each
TabsContentrendersrole="tabpanel"and is named by its tab. - Only the active panel is focusable and exposed; inactive panels are inert.
- Disabled tabs use
aria-disabledand cannot be activated. - Focus is always visible through the shared focus ring token.
- The indicator is decorative and does not affect the accessible name.
- Motion respects
prefers-reduced-motion.
Props#
Tabs#
| Prop | Type | Default |
|---|---|---|
value | string | — |
| Controlled value of the active tab. | ||
defaultValue | string | — |
| Initial value for uncontrolled usage. Defaults to the first enabled tab. | ||
onValueChange | (value, eventDetails) => void | — |
| Called when the active tab changes. | ||
orientation | 'horizontal' | 'vertical' | 'horizontal' |
| Layout and keyboard axis of the tabs. | ||
disabled | boolean | false |
| Disables the whole tab list while keeping the active panel visible. | ||
className | string | — |
| Additional class for the root element. | ||
TabsList#
| Prop | Type | Default |
|---|---|---|
variant | 'underline' | 'pills' | 'enclosed' | 'underline' |
| Visual style of the tab strip. | ||
size | 'sm' | 'md' | 'lg' | 'md' |
| Tab size. | ||
fullWidth | boolean | false |
| Stretches a horizontal list and divides its width between the tabs. | ||
activationMode | 'automatic' | 'manual' | 'automatic' |
| Whether arrow-key focus activates a tab or waits for Enter or Space. | ||
loop | boolean | true |
| Wraps keyboard focus at the ends of the list. | ||
className | string | — |
| Additional class for the list element. | ||
TabsTrigger#
| Prop | Type | Default |
|---|---|---|
value | string | — |
| Value that links the tab to its panel. Required. | ||
disabled | boolean | false |
| Disables this tab. | ||
icon | LucideIcon | — |
| Decorative icon rendered before the label. | ||
badge | ReactNode | — |
| Count or status marker rendered after the label. | ||
className | string | — |
| Additional class for the trigger. | ||
TabsContent#
| Prop | Type | Default |
|---|---|---|
value | string | — |
| Value of the tab that shows this panel. Required. | ||
keepMounted | boolean | false |
| Keeps the panel in the DOM while hidden. Use with care: it preserves form and component state but also costs runtime memory. | ||
className | string | — |
| Additional class for the panel. | ||
TabsIndicator#
TabsIndicator accepts native span attributes and render. Place it inside TabsList; placing it
elsewhere means it cannot measure the active tab.
| Prop | Type | Default |
|---|---|---|
render | ReactElement | — |
| Replaces the default span element. | ||
className | string | — |
| Additional class for the indicator. | ||