--- title: Tabs description: An open-ended, closable tab collection whose panel renders either in the layout or in a popover anchored to its own tab. source: tabs --- ```tsx title="primitives/tabs/demos/basic.tsx" "use client"; import { Tabs, useTabs } from "@intentface/chat/tabs"; import { IconFile, IconPlus, IconX } from "@tabler/icons-react"; import { Fragment, type ReactNode, useEffect, useRef, useState } from "react"; /* * Document tabs across the window chrome, with the content in a card beneath. * * Both the strip and the viewport take a function, so neither needs a map, a * key, or a subscription of its own. The viewport is one box, not a panel per * tab: switching re-renders the same element rather than mounting a new one. * Close the last tab and nothing is open — an ordinary state here, which is * why this is a toolbar of disclosures rather than an ARIA tablist. */ type Document = { name: string; sections: { heading: string; paragraphs: string[] }[] }; const LOREM = { short: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", medium: "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.", long: "Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.", }; // Different lengths on purpose: switching tabs has to visibly change the // viewport, since that is the thing being demonstrated. const SEEDED: Record = { "doc-1": { name: "Getting started", sections: [ { heading: "Overview", paragraphs: [LOREM.short, LOREM.medium] }, { heading: "Before you begin", paragraphs: [LOREM.long] }, ], }, "doc-2": { name: "Installation", sections: [ { heading: "Package manager", paragraphs: [LOREM.medium] }, { heading: "Peer dependencies", paragraphs: [LOREM.short, LOREM.long] }, ], }, "doc-3": { name: "Design tokens", sections: [ { heading: "Surfaces", paragraphs: [LOREM.long, LOREM.short] }, { heading: "State", paragraphs: [LOREM.medium] }, { heading: "Typography", paragraphs: [LOREM.short] }, ], }, "doc-4": { name: "Accessibility", sections: [{ heading: "Roles", paragraphs: [LOREM.medium] }], }, }; export const Basic = () => { const [documents, setDocuments] = useState(SEEDED); return (

{/* The list iterates the collection itself, which leaves no room inside it for chrome — so the add button is its sibling, not its child. The scroller hugs its content, so the button sits beside the last tab until the tabs overflow, then holds the strip's end. */}

{(id) => ( {documents[id]?.name ?? id} {/* Positioned with a mask, so the label runs *under* it and fades out — even a tab squeezed to a few characters keeps a clean edge instead of colliding with the button. It shows itself on hover and while the tab is open. */} )} setDocuments((current) => ({ ...current, [id]: document }))} />

{/* Hidden rather than absent when nothing is open, so the card's place in the layout is held. */} {(id) => }

); }; /* * The scrolling half of the strip. Its edges fade only where tabs are hidden * behind them — see ScrollMask below — and the open tab is brought into view * whenever the selection moves, since a tab added at the end would otherwise * open off-screen. */ const TabStrip = ({ children }: { children: ReactNode }) => { const ref = useRef(null); const value = useTabs((tabs) => tabs.value); // biome-ignore lint/correctness/useExhaustiveDependencies: `value` is the trigger, not an input — the open tab is found off the DOM, and this has to re-run whenever the selection moves. useEffect(() => { ref.current ?.querySelector("[data-tabs-trigger][data-selected]") ?.scrollIntoView({ block: "nearest", inline: "nearest" }); }, [value]); return (

{children}

); }; /* * Scroll-position-driven edge fades, with no JavaScript: a scroll timeline * animates two registered custom properties, and those feed the mask. At the * start the left mask is fully opaque; from 10% in, it fades. The right mask * does the reverse. Unsupported browsers get hard edges, which is fine. * After https://twilson.net/scroll-mask. */ const ScrollMask = () => ( ); /** `open()` adds the tab and selects it in one move — nothing here cleans up. */ const NewDocument = ({ onCreate }: { onCreate: (id: string, document: Document) => void }) => { const open = useTabs((tabs) => tabs.open); const [drafts, setDrafts] = useState(0); return ( ); }; // Left-aligned with a deep left pad, not centred — centring in a wide card // pushes the prose into the middle and leaves it looking adrift. const DocumentBody = ({ document }: { document: Document | undefined }) => { if (!document) return null; return (

{document.name}

{document.sections.map((section) => (

{section.heading}

{section.paragraphs.map((paragraph) => (

{paragraph}

))} ))}

); }; /* * The selected tab is lifted onto a card. `group/tab` is declared here rather * than on the strip, which is what lets `Action` reveal itself on hover without * the strip knowing the group's name. * * `relative` and `overflow-hidden` are both load-bearing: the action positions * against this box, and the label has to clip under it. */ const tabClass = [ "group/tab relative flex h-7 max-w-56 shrink-0 cursor-pointer select-none items-center gap-1.5 overflow-hidden", "rounded-md px-2.5 text-[#686868] text-sm transition-[background-color,color] duration-200 dark:text-[#9b9b9b]", "hover:bg-[#f4f4f4] dark:hover:bg-[#232323]", "focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]", // A real border, transparent until selected. A shadow ring would sit outside // the box, and the scroller clips anything past its content height. "border border-transparent data-[selected]:border-[#f0f0f0] data-[selected]:bg-white data-[selected]:text-[#1a1a1a]", "dark:data-[selected]:border-[#262626] dark:data-[selected]:bg-[#181818] dark:data-[selected]:text-[#fcfcfc]", ].join(" "); ``` ## Usage guidelines - **Open-ended and closable** — tabs are added and removed at runtime, unlike a fixed set of panels. - **Open-ness is the selection** — there is no separate `open` flag. `value` is a tab id or `null`, and `null` means nothing is showing. A page-tab strip never reaches `null`; a chat dock does, every time you close the last one. - **Order is data** — `items` is an ordered array on the store, not something derived from the DOM. Drag it with whatever library you like through `render`; the result is a state change like any other. - **One viewport, not a panel per tab** — switching re-renders the same box, which is what lets a floating surface move rather than tear itself down. - **In the layout or anchored** — wrapping the viewport in `Portal` › `Positioner` › `Popup` is the entire difference between the two. - **A toolbar, not a tablist** — see [Why a toolbar and not a tablist](#why-a-toolbar-and-not-a-tablist). ARIA's tablist cannot describe a closable, open-ended strip. - **Get started** — see [Quick start](/quick-start) to add the package. ## Anatomy ```tsx {/* In the layout … */} {/* … or floating over the open tab. */} ``` One viewport per collection, in one of those two places — the three wrapping parts are the only difference between them. Both the strip and the viewport take a function, so neither needs a loop, a key, or a subscription of its own: ```tsx {(id) => ( {documents[id].title} )} {(id) => } ``` The viewport can sit anywhere in the tree — inside the popup for a floating surface, or in a card three components away while the strip stays in the window chrome. ## Examples ### Anchoring the panel to its tab Wrap the viewport and the panel floats above the open tab instead of sitting in the layout. Nothing else changes — same Root, same List, same ARIA — because the content portals into the viewport wherever it happens to be: ```tsx title="primitives/tabs/demos/anchored.tsx" "use client"; import { Composer, type ComposerSubmitData } from "@intentface/chat/composer"; import { Message } from "@intentface/chat/message"; import { Tabs, useTabs } from "@intentface/chat/tabs"; import { Thread } from "@intentface/chat/thread"; import { IconArrowUp, IconMessage, IconMinus, IconSparkles, IconX } from "@tabler/icons-react"; import { useState } from "react"; /* * A chat dock in the corner of a page. The same Root, List and Viewport as the * document strip, with the viewport wrapped in Portal › Positioner › Popup — * that wrapping is the entire difference between a panel in the layout and one * floating over the open tab. * * What floats is a real chat, built from this package's own parts: a Thread * with Messages and a docked Composer. One positioner serves the whole * collection, anchored to whichever tab is open, so switching chats moves one * surface rather than tearing it down. * * The store handle is created outside React. `Tabs.Root` takes it, and so does * `start` below — which runs in the component that *renders* the Root and so * is not a descendant of it. That is what the handle is for: state a command * palette or a keyboard shortcut elsewhere on the page can reach. Anything * inside the Root reads it through `useTabs` instead. */ const dockStore = Tabs.createStore(); /** The draft's value. It is never in `items` — that is the whole point. */ const DRAFT = "new-chat"; type Turn = { id: string; role: "user" | "assistant"; text: string }; type Chat = { name: string; turns: Turn[] }; const REPLIES = [ "Right — and the reason is that a function is compared by identity, so a fresh one each render reads as a change.", "In this case, nothing: the parent only re-renders when its own state moves, and none of it does here.", "It depends what is downstream of it. A memo-wrapped child cares; a plain one doesn't.", ]; // Different lengths on purpose: switching tabs has to visibly change the // panel, since that is what the dock is here to demonstrate. const SEEDED: Record = { "chat-1": { name: "Notes", turns: [ { id: "1", role: "user", text: "What's the difference between useMemo and useCallback?" }, { id: "2", role: "assistant", text: "useMemo caches a computed value; useCallback caches a function reference. useCallback(fn, deps) is just useMemo(() => fn, deps).", }, { id: "3", role: "user", text: "So when do I actually need useCallback?" }, { id: "4", role: "assistant", text: REPLIES[2] as string }, ], }, "chat-2": { name: "Follow-up", turns: [ { id: "1", role: "user", text: "Does the parent re-render when I pass a new callback?" }, { id: "2", role: "assistant", text: REPLIES[1] as string }, ], }, "chat-3": { name: "Summary", turns: [ { id: "1", role: "user", text: "Summarise the thread so far." }, { id: "2", role: "assistant", text: "Cache values with useMemo, cache functions with useCallback, and reach for either only when something downstream is memoised.", }, { id: "3", role: "user", text: "Why does identity matter for the function case?" }, { id: "4", role: "assistant", text: REPLIES[0] as string }, { id: "5", role: "user", text: "Got it." }, { id: "6", role: "assistant", text: "That's the whole of it." }, ], }, }; let created = 0; export const Anchored = () => { const [chats, setChats] = useState(SEEDED); // The frame stands in for the window. Portaling into it makes it the // collision boundary — the surface shifts and sizes against the demo rather // than the browser viewport. A real dock leaves `container` alone. const [frame, setFrame] = useState(null); const title = (id: string) => (id === DRAFT ? "New chat" : (chats[id]?.name ?? id)); const reply = (id: string, text: string) => setChats((current) => { const chat = current[id]; if (!chat) return current; const next = chat.turns.length; return { ...current, [id]: { ...chat, turns: [ ...chat.turns, { id: `${next}-u`, role: "user", text }, { id: `${next}-a`, role: "assistant", text: REPLIES[next % REPLIES.length] as string }, ], }, }; }); /** A chat the visitor started is titled by what they typed. */ const start = (text: string) => { created += 1; const id = `chat-new-${created}`; setChats((current) => ({ ...current, [id]: { name: text.length > 34 ? `${text.slice(0, 34)}…` : text, turns: [ { id: "1", role: "user", text }, { id: "2", role: "assistant", text: REPLIES[0] as string }, ], }, })); // Adds the tab, selects it, and drops the draft in the same move — nothing // here has to clean anything up. dockStore.getSnapshot().open(id); }; return (

{/* The page the dock sits over. */}

Getting started

A chat dock is something you work behind: non-modal throughout, with no backdrop, no scroll lock, no focus trap, and no dismissal on outside press. Open a chat below, then keep reading — the page stays yours.

The Agent button is a trigger written outside the list. Its value is never in the collection, so it anchors a draft to itself without creating a tab — send something and a tab appears, titled by what you typed.

{/* A row in the layout rather than a fixed overlay, so it sits beside the content instead of on top of it. */}

{(id) => ( {title(id)} )} {/* Outside the list: it takes an explicit value and keeps its own tab stop rather than joining the roving focus — but it carries the same disclosure ARIA a tab does. */} Agent {frame && ( {/* Sized against the room the positioner measured, rather than guessing and overflowing the frame. */} {(id) => id === DRAFT ? ( ) : ( // Keyed so a different chat gets a fresh scroll position // and an empty composer, rather than inheriting the last one's. reply(id, text)} /> ) } )}

); }; /** * One header for the collection, not one per panel — including over the draft, * which otherwise has no way to dismiss itself short of hitting Agent again. */ const DockHeader = ({ title }: { title: (id: string) => string }) => { const open = useTabs((tabs) => tabs.value); const select = useTabs((tabs) => tabs.select); const close = useTabs((tabs) => tabs.close); const isDraft = open === DRAFT; return (

{open === null || isDraft ? null : title(open)}

); }; // Thread measures its docked composer and publishes the reserve as // --thread-overlay-bottom-height, so the last message never hides behind it. const ChatThread = ({ chat, onSend, }: { chat: Chat | undefined; onSend: (text: string) => void; }) => { if (!chat) return null; // `bottom` rather than the default `follow`: it is the one mode that reserves // no viewport for the last turn. In a dock this small the reserve would push // every earlier turn out of sight, so each chat would look like one exchange. return (

{chat.turns.map((turn, index) => ( {turn.text} ))}

); }; /** * A chat that does not exist yet. The one place real words survive: a draft * that looks like an empty chat gives no hint that sending it creates a tab. */ const NewChat = ({ onStart }: { onStart: (text: string) => void }) => (

Ask the agent

This is a draft — it becomes a tab once you send something.

); // The composer clears itself on submit, so the handler only has to act on the // text. Every Composer.Root owns an isolated store — no setup beyond onSubmit. const DockComposer = ({ placeholder, onSubmit, }: { placeholder: string; onSubmit: (text: string) => void; }) => { const handleSubmit = (data: ComposerSubmitData) => { if (data.kind !== "message") return; const text = data.text.trim(); if (text) onSubmit(text); }; return ( ); }; const dockTabClass = [ "group/tab relative flex h-7 max-w-40 shrink-0 cursor-pointer select-none items-center gap-1.5 overflow-hidden", "rounded-md px-2.5 text-[#686868] text-sm transition-colors dark:text-[#9b9b9b]", "hover:bg-[#f4f4f4] dark:hover:bg-[#232323]", "focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]", "data-[selected]:bg-[#ececec] data-[selected]:text-[#1a1a1a] dark:data-[selected]:bg-[#2d2d2d] dark:data-[selected]:text-[#fcfcfc]", ].join(" "); const iconButtonClass = "grid size-6 shrink-0 cursor-pointer select-none place-items-center rounded-md text-[#949494] transition-colors hover:bg-[#f4f4f4] hover:text-[#1a1a1a] focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:text-[#6f6f6f] dark:hover:bg-[#232323] dark:hover:text-[#fcfcfc] dark:focus-visible:outline-[#fcfcfc]"; ``` The panel is a real chat, built from this package's own parts — a [Thread](/primitives/thread) of [Messages](/primitives/message) with a docked [Composer](/primitives/composer). The dock owns *which* conversation is showing; everything inside the panel is the chat primitives' business. ```tsx {/* … */} {(id) => } ``` Note the Agent button in the demo: a `Tabs.Trigger` written *outside* the list, whose value is never in `items`. It anchors a panel to itself without creating a tab — a draft, in other words — and it keeps its own tab stop rather than joining the roving focus. Selecting something else is all it takes to discard it, because there was never a tab to clean up. One positioner serves the whole collection, anchored to whichever tab is open. A positioner per tab would mean an `autoUpdate` loop each — a ResizeObserver and an IntersectionObserver apiece, still running while closed — and nothing to morph between when the selection moves. The surface is non-modal throughout: no backdrop, no scroll lock, no focus trap, and no dismissal on outside press. A chat dock is something you work *behind*. `Positioner` owns the movement and `Popup` owns the appearance, so the element being animated is never the element being moved. Until the first placement lands the surface withholds paint rather than showing at 0,0 — otherwise the first real position would arrive as `auto` → a length, which CSS cannot interpolate, and the surface would slide in from the corner. ### Choosing where the selection lands Where the selection goes when the open tab is closed is a behaviour, and the primitive will not invent one you did not ask for. `selectOnClose` is the only difference between the three strips below. export const closePolicies = [ { value: "unset", default: true, description: "Nowhere: closing what was open shows nothing." }, { value: '"adjacent"', description: "Whatever slides into the vacated slot, or the last tab if the tail went — an editor's behaviour." }, { value: '"recent"', description: "The tab you were in before this one, falling back to adjacent." }, ]; ```tsx title="primitives/tabs/demos/closing.tsx" "use client"; import { Tabs } from "@intentface/chat/tabs"; import { IconArchive, IconInbox, IconPencil, IconSend, IconX } from "@tabler/icons-react"; import { createElement } from "react"; /* * The three close policies side by side. Close the open tab in each strip and * watch where the selection lands. * * `selectOnClose` is the whole difference between them — every other prop is * identical. Leaving it unset is not an oversight: a dock that shows nothing * after you close the last panel is a legitimate resting state, and the * primitive will not pick a successor you did not ask for. */ export const Closing = () => (

); const TABS = ["Inbox", "Drafts", "Sent", "Archive"]; const Strip = ({ policy, caption, }: { policy: "unset" | "adjacent" | "recent"; caption: string; }) => (


      {policy === "unset" ? "selectOnClose unset" : `selectOnClose="${policy}"`}

{(id) => ( {createElement(TAB_ICONS[id] ?? IconInbox)} {id} )} {(id) => {id}}

{caption}

); const tabClass = [ // No strip behind the tabs: they sit on the page ground, and the open one is // a white card matching the panel below, so the selection reads as continuous // with its content rather than as a highlighted button. "group/tab relative flex h-8 w-40 shrink-0 cursor-pointer select-none items-center gap-2 overflow-hidden", // pr-7 reserves the close button's slot permanently. Overlaying it would // cover the label on any short title, and padding it in on hover would make // every tab jump the moment you point at one. "rounded-lg pr-7 pl-2.5 text-[#686868] text-sm transition-colors dark:text-[#9b9b9b]", "hover:bg-[#e7e7e7] dark:hover:bg-[#262626]", "focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]", "data-[selected]:bg-white data-[selected]:text-[#1a1a1a] data-[selected]:shadow-[0_1px_2px_rgba(0,0,0,0.06)]", "dark:data-[selected]:bg-[#2d2d2d] dark:data-[selected]:text-[#fcfcfc]", ].join(" "); /* Per-tab icons rather than one generic page glyph — a strip of identical icons carries no information, and the whole point of a tab icon is telling the tabs apart at a glance. */ const TAB_ICONS: Record = { Inbox: IconInbox, Drafts: IconPencil, Sent: IconSend, Archive: IconArchive, }; ``` ### Persisting the collection The collection goes out through `onItemsChange` and the selection through `onValueChange`, and both come back in as `defaultItems` and `defaultValue`. ```tsx save({ items })} onValueChange={(value) => save({ value })} > ``` A restored selection naming a tab that is no longer in `items` is dropped rather than trusted, so a stale value cannot open a panel for something that does not exist. See [Shell](/primitives/shell#persisting-across-sessions) for why the value has to arrive as a prop rather than be read at init. ### Opening a tab from elsewhere `useTabsStore(store, selector)` is the outside-the-tree twin of `useTabs`, taking an explicit `Tabs.createStore()` handle — which is how a "new chat" button somewhere else in the app opens a tab. There is no global fallback. `open` adds a tab and selects it, or moves and selects one already present, so the caller never has to check first. ```tsx title="primitives/tabs/demos/external.tsx" "use client"; import { Tabs, type TabsStore, useTabsStore } from "@intentface/chat/tabs"; import { IconArchive, IconInbox, IconPencil, IconSend, IconX } from "@tabler/icons-react"; import { createElement, useState } from "react"; /* * Opening a tab from somewhere else in the app. * * `Tabs.createStore()` is the handle. Pass it to the Root and the buttons * below — siblings of the Root, not descendants — can call the same actions * the strip calls. This is how a "new chat" button in the window chrome opens * a tab in a dock it has no path to through context. * * `open` adds a tab and selects it, or moves and selects one already present, * so the button is idempotent without the caller checking first. */ export const ExternalTabs = () => { const [store] = useState(() => Tabs.createStore()); return (

{(id) => ( {createElement(TAB_ICONS[id] ?? IconInbox)} {id} )} {(id) => {id}} {/* Outside Tabs.Root entirely. */}

); }; const DOCUMENTS = ["Drafts", "Sent", "Archive"]; const Launcher = ({ store }: { store: TabsStore }) => { const items = useTabsStore(store, (tabs) => tabs.items); return (

{DOCUMENTS.map((id) => ( ))}

); }; const tabClass = [ // No strip behind the tabs: they sit on the page ground, and the open one is // a white card matching the panel below, so the selection reads as continuous // with its content rather than as a highlighted button. "group/tab relative flex h-8 w-40 shrink-0 cursor-pointer select-none items-center gap-2 overflow-hidden", // pr-7 reserves the close button's slot permanently. Overlaying it would // cover the label on any short title, and padding it in on hover would make // every tab jump the moment you point at one. "rounded-lg pr-7 pl-2.5 text-[#686868] text-sm transition-colors dark:text-[#9b9b9b]", "hover:bg-[#e7e7e7] dark:hover:bg-[#262626]", "focus-visible:-outline-offset-2 focus-visible:outline-2 focus-visible:outline-[#1a1a1a] dark:focus-visible:outline-[#fcfcfc]", "data-[selected]:bg-white data-[selected]:text-[#1a1a1a] data-[selected]:shadow-[0_1px_2px_rgba(0,0,0,0.06)]", "dark:data-[selected]:bg-[#2d2d2d] dark:data-[selected]:text-[#fcfcfc]", ].join(" "); /* Per-tab icons rather than one generic page glyph — a strip of identical icons carries no information, and the whole point of a tab icon is telling the tabs apart at a glance. */ const TAB_ICONS: Record = { Inbox: IconInbox, Drafts: IconPencil, Sent: IconSend, Archive: IconArchive, }; ``` ## Why a toolbar and not a tablist ARIA's `tablist` cannot describe this widget, for two independent reasons. A tablist must own only tabs, so there is nowhere to put a close button; and it requires exactly one selected tab, so `value: null` — a dock with everything closed — is not a state it can express. Both are real, and axe fails the first outright. So the strip is a `toolbar` of buttons, each a disclosure for its panel: `aria-expanded` says whether its panel is showing and `aria-controls` names it. Close buttons are real buttons rather than pointer-only affordances, arrow-key roving focus is exactly what a toolbar is expected to do, and nothing open is an ordinary state. Static, always-one-selected tabs are a different widget, and `tablist` is the right role for those. ## Keyboard export const keys = [ { keys: "Arrow keys", description: "Move focus along the strip, following its orientation." }, { keys: "Enter / Space", description: "Open the focused tab." }, { keys: "Delete / Backspace", description: "Close the focused tab — only inside a Tabs.List, and the keyboard equivalent of the × beside it." }, { keys: "Escape", description: "Close the open panel. The one key bound on the window rather than the strip, since the panel may be portaled away from it — turn it off with dismissOnEscape." }, ]; Focus follows the arrows but does not select, which is what manual activation means; set `activateOnFocus` to select as focus moves. A text field inside the strip keeps the arrow key whenever the caret still has somewhere to travel. ## API reference Every part accepts `className`, `style`, and `render` (see [Styling](/handbook/styling)) and emits a bespoke part attribute (`data-`) unless noted. Every part in the collection also carries `data-orientation`, `data-disabled` when disabled, `data-empty` when nothing is open, and `data-activation-direction`. ### Tabs.Root The provider and container. Renders `data-tabs`. export const rootProps = [ { name: "defaultItems", type: "string[]", description: "The starting tabs when nothing controls them." }, { name: "items", type: "string[]", description: "Controlled collection." }, { name: "onItemsChange", type: "(items: string[]) => void", description: "Fires whenever a tab is added, removed or moved." }, { name: "defaultValue", type: "string | null", description: "The tab open on first render." }, { name: "value", type: "string | null", description: "Controlled selection; null shows nothing." }, { name: "onValueChange", type: "(value: string | null) => void", description: "Fires on every selection change." }, { name: "selectOnClose", type: '"adjacent" | "recent"', description: "Where the selection lands when the open tab is closed. Unset means nowhere." }, { name: "orientation", type: '"horizontal" | "vertical"', default: '"horizontal"', description: "Which arrow keys walk the strip." }, { name: "loop", type: "boolean", default: "true", description: "Wrap at the ends of the strip." }, { name: "activateOnFocus", type: "boolean", default: "false", description: "Select as focus moves, instead of on activation." }, { name: "disabled", type: "boolean", default: "false", description: "Disable the whole collection." }, { name: "dismissOnEscape", type: "boolean", default: "true", description: "Escape closes the open panel." }, { name: "store", type: "TabsStore", description: "An explicit Tabs.createStore() handle. Must be stable for the Root's lifetime." }, ]; export const rootAttrs = [ { attribute: "data-tabs", description: "The container." }, { attribute: "data-orientation", values: '"horizontal" | "vertical"', description: "Which arrow keys walk the strip." }, { attribute: "data-empty", description: "Present while nothing is open. A page-tab strip never sees this; a dock does." }, { attribute: "data-disabled", description: "Present while the whole collection is disabled." }, { attribute: "data-activation-direction", values: '"left" | "right" | "up" | "down"', description: "Which way the selection last moved, for panels that slide rather than fade. Absent when it has not moved." }, ]; ### Tabs.List The strip. Renders `data-tabs-list` with `role="toolbar"` and owns the roving focus. export const listProps = [ { name: "children", type: "ReactNode | ((value: string, index: number) => ReactNode)", description: "Plain children when you lay the strip out yourself; a function renders one call per tab, in order." }, ]; export const listAttrs = [ { attribute: "data-tabs-list", values: 'role="toolbar"', description: "The strip, with aria-orientation matching the Root's." }, { attribute: "data-orientation", values: '"horizontal" | "vertical"', description: "The strip's orientation." }, { attribute: "data-empty", description: "Present while nothing is open." }, { attribute: "data-disabled", description: "Present while the collection is disabled." }, { attribute: "data-activation-direction", values: '"left" | "right" | "up" | "down"', description: "Which way the selection last moved." }, ]; ### Tabs.Trigger One tab. Renders `data-tabs-trigger`, with `aria-expanded` and an `aria-controls` that only claims a viewport really in the document. One part, two situations, decided by where it sits rather than by a prop: inside a `Tabs.List` it joins the collection and the roving focus, and `Delete` closes it. Outside one it takes an explicit value, keeps its own tab stop, and toggles — a panel with no tab behind it, anchored to the button that owns it. export const triggerProps = [ { name: "value", type: "string", description: "The tab's id. Required outside a List; inherited from the enclosing tab inside one." }, { name: "disabled", type: "boolean", description: "Disable this tab. It stays in the arrow-key ring." }, ]; export const triggerAttrs = [ { attribute: "data-tabs-trigger", values: "the tab's value", description: "The tab, and its identity — the strip's roving focus finds tabs by this attribute and reads the value back off it. Select it without the value for styling." }, { attribute: "data-selected", description: "Present while this tab's panel is showing." }, { attribute: "data-disabled", description: "Present while disabled." }, { attribute: "data-orientation", values: '"horizontal" | "vertical"', description: "The strip's orientation." }, ]; ### Tabs.Icon Decoration inside a tab. Renders a `` with `data-tabs-icon` and `aria-hidden` — the trigger already has an accessible name, and an icon that repeats it only makes the announcement longer. It carries the tab's state, so the mark can respond to its tab being open without a group selector. export const iconProps = [ { name: "value", type: "string", description: "Only outside a tab, where there is none to inherit from." }, ]; export const iconAttrs = [ { attribute: "data-tabs-icon", description: "The icon slot." }, { attribute: "data-selected", description: "Present while the tab's panel is showing." }, { attribute: "data-disabled", description: "Present while the tab is disabled." }, ]; ### Tabs.Action The trailing slot inside a tab — where the close button lives. Renders `data-tabs-action`, carrying the tab's state. export const actionProps = [ { name: "value", type: "string", description: "Only outside a tab, where there is none to inherit from." }, ]; export const actionAttrs = [ { attribute: "data-tabs-action", description: "The slot." }, { attribute: "data-selected", description: "Present while the tab's panel is showing." }, { attribute: "data-disabled", description: "Present while the tab is disabled." }, ]; It wants to be **positioned rather than in flow** — a tab narrow enough to truncate has nowhere to put a control, so the label needs to run *under* the button and fade out: ```css [data-tabs-trigger] { position: relative; overflow: hidden; } [data-tabs-action] { position: absolute; inset-block: 0; right: 0; display: flex; align-items: center; /* The padding starts the button past the end of the gradient. */ padding-inline: 0.75rem 0.375rem; background-color: inherit; mask-image: linear-gradient(to right, transparent, #000 0.5rem); } ``` `background-color: inherit` takes the tab's own colour, whatever state it is in, and the mask fades that background in from the left — so the label slides under it rather than stopping at a hard edge. Laying it out in flow instead gives you a button that collides with the label on exactly the tabs where it matters. ### Tabs.Close The × inside a tab. Renders `data-tabs-close` as a `role="button"` with `tabIndex="-1"`, for the same reason its parent is a `div`. It keeps out of the roving order — arrowing along a strip should walk tabs, not alternate between each tab and its close button — so the keyboard route to closing is `Delete` on the tab itself. Every event it handles stops there: nested inside the trigger, anything that escaped would open the tab on its way out of closing it. export const closeProps = [ { name: "value", type: "string", description: "Only outside a tab, where there is none to inherit from." }, { name: "disabled", type: "boolean", description: "Defaults to the tab's disabled state." }, ]; export const closeAttrs = [ { attribute: "data-tabs-close", description: "The close button." }, { attribute: "data-selected", description: "Present while the tab's panel is showing." }, { attribute: "data-disabled", description: "Present while disabled." }, ]; ### Tabs.Viewport The one box that shows a tab's content. Renders `data-tabs-viewport` as a `role="group"` named by whichever tab is open, through `aria-labelledby`. The role is what makes the name stick: a bare `div` maps to `generic`, whose name assistive technology discards. Nothing off-screen exists, and that is deliberate: a tab you are not looking at has no component, so anything that must keep running while you are elsewhere — a reply still streaming — belongs in a store rather than in the panel's state. export const viewportProps = [ { name: "children", type: "(value: string) => ReactNode", description: "Renders the content for whatever is open. Not called when nothing is." }, ]; export const viewportAttrs = [ { attribute: "data-tabs-viewport", description: "The content box. Carries an id, and `aria-labelledby` naming whichever tab is open." }, { attribute: "data-empty", description: "Present while nothing is open — the children function is not called, so the box is empty." }, { attribute: "data-orientation", values: '"horizontal" | "vertical"', description: "The collection's orientation." }, { attribute: "data-activation-direction", values: '"left" | "right" | "up" | "down"', description: "Which way the selection last moved, so the panel can slide the right way." }, ]; The open tab's id is deliberately *not* published as an attribute: it is state the viewport needs, but not a styling hook. ### Tabs.Portal Owns the mounting of the floating surface. Renders no element of its own — so it has no attributes to publish — and keeps its children in the DOM through the exit animation, which `Tabs.Popup` reports as finished. export const portalProps = [ { name: "container", type: "HTMLElement | null", default: "document.body", description: "Where the surface is portaled." }, { name: "keepMounted", type: "boolean", default: "false", description: "Keep the surface mounted while nothing is open. Costs a live positioning loop." }, ]; ### Tabs.Positioner Owns the placement. Renders `data-tabs-positioner` as `role="presentation"`, anchored to whichever tab is open. export const positionerProps = [ { name: "side", type: '"top" | "bottom" | "left" | "right"', default: '"top"', description: "Preferred side; flips when there is no room." }, { name: "align", type: '"start" | "center" | "end"', default: '"center"', description: "Alignment along that side." }, { name: "sideOffset", type: "number", default: "8", description: "Gap between the tab and the surface." }, { name: "collisionPadding", type: "number", default: "8", description: "How far clear of the viewport edges to stay." }, ]; Placement lands on the positioner, which is also where the measured geometry is published — `position`, `left` and `top` are written imperatively, so do not set them from a stylesheet on this part. export const positionerAttrs = [ { attribute: "data-tabs-positioner", values: 'role="presentation"', description: "The positioned wrapper." }, { attribute: "data-open", description: "Present while a tab is open." }, { attribute: "data-closed", description: "Present while nothing is." }, { attribute: "data-side", values: '"top" | "bottom" | "left" | "right"', description: "The resolved side, which flip may have changed — so a surface that flipped can style itself as where it ended up." }, { attribute: "data-align", values: '"start" | "center" | "end"', description: "The resolved alignment." }, { attribute: "--anchor-width", values: "measured px", description: "The open tab's own width, e.g. so a surface can match it." }, { attribute: "--anchor-height", values: "measured px", description: "The open tab's own height." }, { attribute: "--anchor-available-width", values: "measured px", description: "Free space toward the placement side — cap a max-width instead of overflowing." }, { attribute: "--anchor-available-height", values: "measured px", description: "The same, vertically." }, ]; ### Tabs.Popup The surface itself: the part to style and animate. Renders `data-tabs-popup`, and it is what reports the exit animation as finished so the portal knows when to unmount. export const popupAttrs = [ { attribute: "data-tabs-popup", description: "The surface." }, { attribute: "data-open", description: "Present while a tab is open." }, { attribute: "data-closed", description: "Present while nothing is." }, { attribute: "data-starting-style", description: "Present on the first open frame." }, { attribute: "data-ending-style", description: "Present while the exit animation runs." }, ]; ## useTabs Read the collection from anywhere inside ``: ```tsx const openTab = useTabs((tabs) => tabs.value); ``` export const hookMembers = [ { name: "value", type: "string | null", description: "The open tab, or null when nothing is." }, { name: "items", type: "string[]", description: "The tabs, in order." }, { name: "recent", type: "string[]", description: "Most recently opened first — what the recent close policy reads." }, { name: "direction", type: '"left" | "right" | "up" | "down" | "none"', description: "Which way the selection last moved, for panels that slide rather than fade." }, { name: "open", type: "(value, options?) => void", description: "Add a tab (or move it, if already present) and select it." }, { name: "close", type: "(value: string) => void", description: "Remove a tab; selectOnClose decides where the selection lands." }, { name: "select", type: "(value: string | null) => void", description: "Open a tab, or null to show nothing." }, { name: "selectRelative", type: "(direction, options?) => void", description: "Step the selection — what the arrow keys drive." }, { name: "move", type: "(value: string, toIndex: number) => void", description: "Reorder; the target index is clamped into range." }, { name: "setItems", type: "(items: string[]) => void", description: "Replace the whole collection." }, ]; `useTabsStore(store, selector)` is the outside-the-tree twin, taking an explicit `Tabs.createStore()` handle — which is how a "new chat" button somewhere else in the app opens a tab. There is no global fallback.