--- name: tabs-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit Tabs for switching peer content panels with Zag.js tabs behavior, compound list, triggers, content, indicator, orientation, activation mode, variants, fitted, and justify props. metadata: component_version: "2.0.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "https://zagjs.com/components/react/tabs" contributor_sources: "libs/ui/src/molecules/tabs.tsx libs/ui/src/tokens/components/molecules/_tabs.css libs/ui/stories/molecules/tabs.stories.tsx libs/ui/src/molecules/tabs.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Tabs Usage Use Tabs for peer panels in the same page context. Use Steps for ordered workflow progress and Breadcrumb for hierarchy. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Tabs`. **Use it when** - Peer views of the same object or page: record sections (Content, SEO, History), settings groups (vertical). **Use something else when** | Need | Use instead | | --- | --- | | Sequential steps | Steps | | Optional expandable content | Accordion | | Navigation between pages | links / Sidebar | | Two views of the same data (table/grid) | a segmented control or icon toggle | **Do** - Keep labels short (1–2 words) and the first tab the content users came for. - Preserve the active tab in the URL for linkable settings/records. - Show errors in a tab's label (count badge) when the invalid field is in a hidden tab. **Don't** - Nest tabs inside tabs. - Use tabs when users must compare content across tabs. **Copy and states** - Nouns in sentence case; counts in parentheses or a Badge (`Orders 12`). **Behaviour (from the UX spec)** - Use one `activationMode` per set; choose `"manual"` when switching a panel is expensive (loads data). - Switching tabs never commits or discards data; a form in a panel keeps its draft. - The selected tab always matches the panel shown; the indicator moves only when the panel changes, never on hover. Focus alone never selects in `activationMode="manual"`; in `"automatic"` (the default) arrow keys move focus and select the tab. **Figma → code** | Figma | Code | | --- | --- | | `appearance`, `size`, `orientation` | `appearance`, `size`, `orientation` | | `state=selected` | `value` / `defaultValue` | | `state=disabled` | `disabled` on `Tabs.Trigger` | | — | `activationMode`, `fitted`, `justify` (not in Figma) | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Tabs → UX guidelines*. ## Setup ```tsx Details Reviews Details content Reviews content ``` Supported props: ```text appearance: underline | line | solid | outline size: sm | md | lg orientation: horizontal | vertical activationMode: automatic | manual fitted, justify start | center | end value/defaultValue, loopFocus, onValueChange ``` ## Core Patterns ### Match trigger and content values Every trigger value should have matching content value. ### Use line variant with indicator `Tabs.Indicator` is meaningful for `line`; other variants hide it. ### Do not use Tabs for navigation pages If changing the URL/page hierarchy, use Link/Breadcrumb/Pagination. ## Common Mistakes ### HIGH Button state tabs Wrong: ```tsx {tab === "a" &&
} ``` Correct: ```tsx Overview Delivery Product specifications. Dispatch within two working days. ``` Source: libs/ui/src/molecules/tabs.tsx ### HIGH Value mismatch Wrong: ```tsx ``` Correct: ```tsx {/* Partial fragment inside the Setup structure, not a standalone tab group. */} Details Product dimensions and materials. ``` Source: https://zagjs.com/components/react/tabs ### HIGH Inline selected styling Wrong: ```tsx ``` Correct: ```tsx Overview Delivery Product specifications. Dispatch within two working days. ``` Source: libs/ui/src/tokens/components/molecules/_tabs.css ## Validation Commands ```sh rg -n "setTab|]*className=.*(bg-|text-|border-|data-\\[selected)" apps rg -P -n "]*value=)|]*value=)" apps rg -n "]*(variant=|appearance=\"(primary|default)\")" apps ``` ## Template default selection TabsTemplate selects the first enabled item when defaultValue is omitted. An explicit value/defaultValue still takes precedence. Keep trigger values matched to content and give every tab list a contextual accessible name where needed. Canonical sizes are sm/md/lg (default md). Use headings within panels rather than nested tabs, as shown by the sectioned-content story. Horizontal lists scroll within their available width on narrow surfaces. Trigger focus rings are inset so the scroll viewport cannot clip them. Content and root containers keep min-width zero; callers should constrain fixed demonstration widths with max-w-full. Center/end justification falls back to start when tabs overflow, keeping the first tab reachable. Line indicators stay inside the scrollport; default tabs underline the selected label even without an Indicator. Vertical strips retain their intrinsic label width rather than being squeezed by panel content. Panels take the remaining space and wrap long unbroken text; keep vertical tab labels short so both columns remain useful on narrow screens. ## Collection changes and keyboard entry `Tabs.List` is required, not just a layout wrapper: it provides tablist semantics and arrow/Home/End handling. Give every list a contextual accessible name. `TabsTemplate` accepts `tablistProps` (for example, `aria-labelledby` pointing to a visible heading); root ARIA props still apply to the outer root. Uncontrolled tabs select the first enabled trigger after an empty collection is populated. If selection disappears or becomes disabled, the next surviving neighbor is selected, then the previous neighbor, then the first enabled tab. This preserves surviving panel state. Empty/all-disabled lists have no keyboard entry until an enabled trigger appears. Controlled values remain parent-owned: an invalid value requests the same fallback through `onValueChange` once per invalid-value/fallback pair. A rejecting owner leaves panels unselected, but an enabled trigger remains a keyboard entry point. Accept the request to keep panel data and selection aligned. Focus only recovers when the affected trigger/panel owned it; changes elsewhere do not steal focus. Focused/selected horizontal tabs scroll within their own strip, including manual activation and RTL. Only one trigger drives strip scrolling at a time, so the selected underline stays beneath its own tab. The indicator tracks the selected tab across selection, keyboard navigation, strip scrolling and layout shifts in LTR and RTL, measured in its own containing block instead of a cached rectangle.