Tabs
A tab strip with one panel per tab. Compose it from Tabs.List holding
one Tabs.Trigger per tab, and one
Tabs.Content per tab. The first tab is selected until the user picks
another, and a selection whose tab is gone falls back to the first.
Built on bits-ui Tabs.
<Tabs bind:value> <Tabs.List aria-label="Details"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="usage">Usage</Tabs.Trigger> </Tabs.List> <Tabs.Content value="overview">…</Tabs.Content> <Tabs.Content value="usage">…</Tabs.Content></Tabs>Overview panel
Usage panel
API panel
- Composed from parts, so the list, each tab, and each panel are yours to arrange.
- The first tab is selected until the user picks another. A selection whose tab is removed falls back to the first remaining tab.
valueon the root is bindable, two-way or as a getter and setter. State & binding explains both modes.- Activation is automatic: ArrowLeft, ArrowRight, Home, and End move focus and select.
- Each
Tabs.Triggeris arole="tab"element, not a<button>, so a control can sit inside it. - A strip with one tab is a bar with nothing to switch between. Wrap
Tabs.Listin{#if}when the count can drop to one. - Navigation tabs, links marked with
aria-current, are styled anchors, not this component.
Anatomy
Section titled “Anatomy”Every part is a property on Tabs. Pair each Tabs.Trigger with a Tabs.Content that has the same value. Name the strip with aria-label or aria-labelledby on Tabs.List.
<Tabs> <Tabs.List aria-label="Details"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="usage">Usage</Tabs.Trigger> </Tabs.List> <Tabs.Content value="overview">...</Tabs.Content> <Tabs.Content value="usage">...</Tabs.Content></Tabs>Two-way binding
Section titled “Two-way binding”bind:value on the root holds the value of the selected tab.
Overview panel
Usage panel
API panel
value: undefined
Code
<script lang="ts"> import { Tabs } from "@viamrobotics/prime-ui";
let value = $state<string>();</script>
<div class="not-content flex w-full max-w-md flex-col gap-2"> <Tabs bind:value> <Tabs.List aria-label="Details"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="usage">Usage</Tabs.Trigger> <Tabs.Trigger value="api">API</Tabs.Trigger> </Tabs.List> <Tabs.Content value="overview"><p class="py-3 text-sm">Overview panel</p></Tabs.Content> <Tabs.Content value="usage"><p class="py-3 text-sm">Usage panel</p></Tabs.Content> <Tabs.Content value="api"><p class="py-3 text-sm">API panel</p></Tabs.Content> </Tabs> <p class="text-xs text-subtle-2">value: {String(value)}</p></div>Fully controlled
Section titled “Fully controlled”Pass bind:value a getter and a setter. The setter can decline a change.
Overview panel
Usage panel
Code
<script lang="ts"> import { Tabs } from "@viamrobotics/prime-ui";
let value = $state("overview"); let isLocked = $state(true);</script>
<div class="not-content flex w-full max-w-md flex-col gap-3"> <label class="flex items-center gap-2 text-sm"> <input type="checkbox" bind:checked={isLocked} /> Keep the first tab selected </label>
<Tabs bind:value={ () => value, (next) => { if (!isLocked) value = next; } } > <Tabs.List aria-label="Details"> <Tabs.Trigger value="overview">Overview</Tabs.Trigger> <Tabs.Trigger value="usage">Usage</Tabs.Trigger> </Tabs.List> <Tabs.Content value="overview"><p class="py-3 text-sm">Overview panel</p></Tabs.Content> <Tabs.Content value="usage"><p class="py-3 text-sm">Usage panel</p></Tabs.Content> </Tabs></div>A trigger’s children are its content, so an icon sits beside the label.
Metrics panel
Settings panel
Code
<script lang="ts"> import { mdiChartLine, mdiCog } from "@mdi/js"; import { Icon, Tabs } from "@viamrobotics/prime-ui";</script>
<div class="not-content w-full max-w-md"> <Tabs> <Tabs.List aria-label="Sections"> <Tabs.Trigger value="metrics" class="flex items-center gap-1.5"> <Icon icon={mdiChartLine} size="sm" /> Metrics </Tabs.Trigger> <Tabs.Trigger value="settings" class="flex items-center gap-1.5"> <Icon icon={mdiCog} size="sm" /> Settings </Tabs.Trigger> </Tabs.List> <Tabs.Content value="metrics"><p class="py-3 text-sm">Metrics panel</p></Tabs.Content> <Tabs.Content value="settings"><p class="py-3 text-sm">Settings panel</p></Tabs.Content> </Tabs></div>Controls inside a tab
Section titled “Controls inside a tab”Put controls in the actions snippet of Tabs.Trigger, after the label. The tab is then named from its label alone, so a close button’s name does not leak into it. A control nested in a tab keeps its own key events, so Enter and Space reach it. Its click handler should call event.stopPropagation(), or the click also selects the tab. Closing the selected tab falls back to the first remaining tab, and the list hides at one tab.
Close the selected tab and selection falls back to the first. At one tab the list hides.
Close the selected tab and selection falls back to the first. At one tab the list hides.
Close the selected tab and selection falls back to the first. At one tab the list hides.
Code
<script lang="ts"> import { mdiClose } from "@mdi/js"; import { Icon, Tabs } from "@viamrobotics/prime-ui";
let ids = $state([1, 2, 3]); let next = 4;
const close = (event: MouseEvent, n: number) => { event.stopPropagation(); ids = ids.filter((existing) => existing !== n); };
const add = () => { ids = [...ids, next]; next += 1; };</script>
<div class="not-content flex w-full max-w-md flex-col gap-3"> <Tabs> {#if ids.length > 1} <Tabs.List aria-label="Documents"> {#each ids as n (n)} <Tabs.Trigger value="tab-{n}" class="flex items-center gap-1.5"> Tab {n} {#snippet actions()} <button type="button" class="icon-button" aria-label="Close Tab {n}" onclick={(event) => close(event, n)} > <Icon icon={mdiClose} size="sm" /> </button> {/snippet} </Tabs.Trigger> {/each} </Tabs.List> {/if} {#each ids as n (n)} <Tabs.Content value="tab-{n}"> <p class="py-3 text-sm"> Close the selected tab and selection falls back to the first. At one tab the list hides. </p> </Tabs.Content> {/each} </Tabs> <button type="button" class="button self-start" onclick={add}>Add tab</button></div>File-style tabs
Section titled “File-style tabs”variant="file" on the root draws compact, boxed tabs like an editor’s file tabs, with the selected tab joined to the content below it. Pick it for a header over documents the user opens and closes, where the tabs are many and each carries a control. Tabs.List and Tabs.Trigger follow the root, so only the root takes the prop. The selected tab scrolls into view, and a strip that overflows scrolls sideways and never wraps.
Contents of main.ts
Contents of config.json
Contents of README.md
Contents of package.json
Contents of tsconfig.json
Contents of styles.css
Contents of utils.ts
Code
<script lang="ts"> import { mdiClose } from "@mdi/js"; import { Icon, Tabs } from "@viamrobotics/prime-ui";
let ids = $state(["main.ts", "config.json", "README.md", "package.json", "tsconfig.json", "styles.css", "utils.ts"]);
const close = (event: MouseEvent, id: string) => { event.stopPropagation(); ids = ids.filter((existing) => existing !== id); };</script>
<div class="not-content w-full max-w-md"> <Tabs variant="file"> <Tabs.List aria-label="Open files"> {#each ids as id (id)} <Tabs.Trigger value={id}> {id} {#snippet actions()} <button type="button" class="icon-button" aria-label="Close {id}" onclick={(event) => close(event, id)} > <Icon icon={mdiClose} size="sm" /> </button> {/snippet} </Tabs.Trigger> {/each} </Tabs.List> {#each ids as id (id)} <Tabs.Content value={id}> <p class="p-3 text-sm">Contents of {id}</p> </Tabs.Content> {/each} </Tabs></div>Reordering
Section titled “Reordering”reorderable on Tabs.List lets the user move tabs, with a pointer drag or the keyboard. It works under both variants. The order is yours to hold: Tabs.List takes a bindable order, the tab values in strip order, and you render the triggers from it in a keyed {#each}. Key each trigger by its value, so a move shuffles the existing tabs instead of rebuilding them. A move writes a new array and changes no selection.
A press on a control inside a tab never starts a drag, so a close button keeps working. A disabled tab cannot be moved.
A drag alone fails WCAG 2.5.7, and the keys need a keyboard. The actions snippet receives movePrevious, moveNext, canMovePrevious, and canMoveNext. Those take the same path as a key, so the move is announced, focus lands on the moved tab, and a binding that refuses the move is honored. The Reorderable example shows them in a tab menu.
Contents of main.ts
Contents of config.json
Contents of README.md
Contents of utils.ts
Order: main.ts, config.json, README.md, utils.ts
Code
<script lang="ts"> import { mdiClose, mdiDotsHorizontal } from "@mdi/js"; import { Icon, Menu, Tabs } from "@viamrobotics/prime-ui";
let order = $state(["main.ts", "config.json", "README.md", "utils.ts"]);
const close = (event: MouseEvent, id: string) => { event.stopPropagation(); order = order.filter((existing) => existing !== id); };</script>
<div class="not-content w-full max-w-md"> <Tabs variant="file"> <Tabs.List aria-label="Open files" reorderable bind:order> {#each order as id (id)} <Tabs.Trigger value={id}> {id} {#snippet actions({ movePrevious, moveNext, canMovePrevious, canMoveNext })} <Menu> <Menu.Trigger class="icon-button" aria-label="Options for {id}"> <Icon icon={mdiDotsHorizontal} size="sm" /> </Menu.Trigger> <Menu.Content aria-label="Options for {id}"> <Menu.Item disabled={!canMovePrevious} onclick={movePrevious}>Move left</Menu.Item> <Menu.Item disabled={!canMoveNext} onclick={moveNext}>Move right</Menu.Item> </Menu.Content> </Menu> <button type="button" class="icon-button" aria-label="Close {id}" onclick={(event) => close(event, id)} > <Icon icon={mdiClose} size="sm" /> </button> {/snippet} </Tabs.Trigger> {/each} </Tabs.List> {#each order as id (id)} <Tabs.Content value={id}> <p class="p-3 text-sm">Contents of {id}</p> </Tabs.Content> {/each} </Tabs> <p class="mt-2 text-sm">Order: {order.join(", ")}</p></div>bind:order also takes a getter and a setter. When the setter leaves order unchanged, the move is refused and the strip stays as it was.
The home panel
The docs panel
The blog panel
The about panel
The home tab is pinned, so any move that displaces it is refused.
Code
<script lang="ts"> import { Tabs } from "@viamrobotics/prime-ui";
let order = $state(["home", "docs", "blog", "about"]);</script>
<div class="not-content w-full max-w-md"> <Tabs> <Tabs.List aria-label="Sections" reorderable bind:order={ () => order, (next) => { if (next[0] === "home") order = next; } } > {#each order as id (id)} <Tabs.Trigger value={id}>{id}</Tabs.Trigger> {/each} </Tabs.List> {#each order as id (id)} <Tabs.Content value={id}> <p class="p-3 text-sm">The {id} panel</p> </Tabs.Content> {/each} </Tabs> <p class="mt-2 text-sm">The home tab is pinned, so any move that displaces it is refused.</p></div>Styling
Section titled “Styling”The root and every part take class on their element. The file variant wears the file-tabs and file-tab classes from tailwind-config. See file-tabs.
| Part | Attribute | Value |
|---|---|---|
Trigger |
data-state |
active or inactive |
Trigger |
data-disabled |
present when disabled |
Content |
data-state |
active or inactive |
Keyboard
Section titled “Keyboard”| Key | Action |
|---|---|
| ArrowLeft / ArrowRight | Moves focus to the previous or next tab and selects it. |
| Home / End | Moves focus to the first or last tab and selects it. |
| Alt + Shift + ArrowLeft / ArrowRight | Moves the focused tab one place left or right, when the list is reorderable. |
| Tab | Moves focus into the selected panel. |
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
bind:value | string | The selected tab's value. Two-way bindable. Defaults to the first tab's. | |
variant | TabsVariant | 'underline' | The strip's look. file is compact, boxed tabs like an editor's file tabs. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Tabs.Content
The panel a Tabs strip shows while the tab with the same value is
selected.
Takes extraClasses, children, ...restProps }: Props as its props.
Tabs.List
The strip that holds a Tabs root’s triggers. Give it an aria-label or
aria-labelledby. A strip with one tab is a bar with nothing to switch between, so render it
only when there are two or more. Under the root’s file variant it is a single row that
scrolls sideways and never wraps.
With reorderable, Alt+Shift+ArrowLeft and Alt+Shift+ArrowRight move the focused tab one place,
dragging a tab drops it where the pointer lets go, and either writes the new strip order to
order. Render the triggers from order in a keyed {#each}.
<Tabs.List aria-label="Files" reorderable bind:order> {#each order as id (id)} <Tabs.Trigger value={id}>{names[id]}</Tabs.Trigger> {/each}</Tabs.List>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
reorderable | boolean | false | Let the keyboard and the pointer move tabs within the strip. |
bind:order | string[] | The tab values in strip order. Two-way bindable. A move writes a new array here, and a function binding can refuse it. Defaults to the triggers' mount order. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Tabs.Trigger
One tab of a Tabs strip. Its children are the tab’s label. It is a
role="tab" element rather than a <button>, so a control such as a close icon-button can
sit inside it, placed through the actions snippet. That control’s keys stay with it, and it
stops click propagation so the click does not select the tab. Under the root’s file variant the tab is a boxed file tab, and
selecting it scrolls the strip to show it.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
value | string | The value the root holds when this tab is selected. | |
disabled | boolean | false | Disable this tab. |
actions | Snippet<[TabsMove]> | Controls placed after the label, such as a close button or Move left and Move right buttons. The
tab is named from children alone unless aria-label or aria-labelledby is given. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.