Tabs
Switch between related panels for the same subject.
Installation
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"Import @commenda/pathfinder/styles.css once after host CSS. Pathfinder ships compiled, prefixed Tailwind v4 CSS; the application needs no Tailwind scanning. Import from @commenda/pathfinder/tabs. Interactive callbacks belong in a client component in Next.js App Router.
API reference
| Prop | Type | Behavior |
|---|---|---|
labelRequired | string | Required; tablist accessible name |
itemsRequired | readonly TabItem[] | Required; value, label, content; optional count and disableConfig |
valueConditional | string|null | Controlled / initial selection; first enabled item if omitted |
defaultValue | string|null | Controlled / initial selection; first enabled item if omitted |
onValueChangeConditional | (
value: string | null
) => void | Required with value |
orientation | "vertical"|"horizontal" | horizontal |
activationMode | "manual"|"automatic" | automatic; use manual for slow remote content |
divider | boolean | true; horizontal only |
panelConfig | ObjectView fields | keepMounted false |
overflowConfig | ObjectView fields | More |
id | string | Stable HTML identifier for the component. |
className | string | Additional classes for the component root. |
panelConfigObject fields
| Field | Type | Requirement |
|---|---|---|
keepMounted | boolean | Optional |
className | string | Optional |
overflowConfigObject fields
| Field | Type | Requirement |
|---|---|---|
label | string | Optional |
Root IDs, className, appropriate ARIA attributes, and typed refs are supported. Controlled value requires onValueChange and cannot be combined with defaultValue. Item IDs/values must be unique and stable.
Usage rules
disableConfig: { isDisabled: boolean; reason?: string } keeps disabled state and its explanation together. Counts are plain numbers, including zero; do not use a Badge or icons inside the tab label.
Horizontal overflow is measured against the container and moves hidden options into More. The active tab stays visible; choosing an overflow item returns focus to its promoted tab. Before measurement, a local scrolling row keeps options reachable. Extremely long active labels remain horizontally scrollable without overflowing the page.
Arrow keys navigate visible tabs; Home/End reach their ends. Automatic mode also selects on arrow focus. Manual mode activates with Enter/Space. More is a separate menu button, reached with Tab. Hidden options remain available in that menu. Disabled options cannot activate. keepMounted retains inactive content without leaving it focusable.
Uncontrolled tabs fall back to the first enabled item after removal/disablement. Controlled callers reconcile changed items and own URL synchronization. null means no active panel. These tabs model related panels, not an unrelated route-only sidebar.
Examples
Vertical
Overflow
Controlled
Design rules
Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.
Tabs
Source: 352:10826, horizontal 352:95, vertical 352:121, docs 354:278.
TABS-01— Source: horizontal height 28, gap 12, Label/12 Strong, 0.5 divider, 2px blue-700 indicator. Counts are plain Label/12 numbers, gap 4; never Badge or icons. Vertical width 180, padding 6/8, radius 6, gap 2, Label/13 Strong, selected pearl-200.TABS-02— Source/Pathfinder: related panels for one subject. First enabled item is the uncontrolled default. Caller controls URL synchronization; unrelated routes use navigation. Indicator 200ms ease-out, no panel animation, reduced motion immediate.TABS-03— Source/Pathfinder: More exposes options that do not fit. Measurement reserves More and the active tab; selected hidden tabs become visible and receive focus. Inert copies measure widths; pre-measurement and exceptionally narrow layouts retain local horizontal scrolling. Never discard a tab to solve overflow.TABS-04— Pathfinder: automatic or manual keyboard activation; disabled items cannot activate. Controlled callers reconcile missing selections; uncontrolled removal/disablement selects the first enabled item. null permits no active panel. keepMounted retains inactive content without focusability; zero counts remain visible.