Tabs
A WAI-ARIA tabs widget: a tablist linked to panels, with arrow navigation.
Import
Section titled “Import”<script> import Tabs from "@invisible-ui/svelte/Tabs.svelte";</script><script setup> import { Tabs } from "@invisible-ui/vue";</script>import { Tabs } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-tabs></ds-tabs>| Prop | Type | Default | Description |
|---|---|---|---|
items * | TabsItem[] | — | |
value | string | null | null | |
activationMode | ActivationMode | "automatic" | |
label * | string | — | Accessible name for the tab list. |
onValueChange | ((value: string) => void) | undefined | undefined | Called whenever the selected tab changes. |
panel | Snippet<[{ item: TabsItem }]> | undefined | undefined | Rich content of one panel, rendered once per tab with its item. |
actions | Snippet | undefined | undefined | Commands beside the tab list, outside it, such as an "add" button. |
| Prop | Type | Default | Description |
|---|---|---|---|
items * | TabsItem[] | — | Ordered list of tabs. |
modelValue | string | null | undefined | v-model value; takes precedence over value when bound. |
value | string | null | null | Selected tab value. null falls back to the first enabled tab. |
activationMode | ActivationMode | "automatic" | automatic (default): arrows select while moving. manual: Enter/Space selects. |
label * | string | — | Accessible name for the tab list (announced by screen readers). |
onValueChange | (value: string) => void | undefined | Called whenever the selected tab changes. |
| Event | Payload |
|---|---|
update:modelValue | value: string |
Slots: actions, panel.
| Prop | Type | Default | Description |
|---|---|---|---|
items * | TabsItem[] | — | |
value | string | null | null | Initial (uncontrolled) or current (controlled) selected tab. |
activationMode | ActivationMode | "automatic" | automatic (default): arrows select while moving. manual: Enter or Space selects. |
label * | string | — | Accessible name for the tab list (announced by screen readers). |
onValueChange | (value: string) => void | — | Called whenever the selected tab changes. |
renderPanel | (item: TabsItem) => ReactNode | — | Rich content of one panel, rendered once per tab; wins over content. |
actions | ReactNode | — | Commands beside the tab list, outside it, such as an "add" button. |
| Attribute | Reactive | Description |
|---|---|---|
label * | yes | for the shortcut; composed tabs name their <ds-tab-list> |
value | yes | |
activation-mode | yes | automatic|manual |
Reactive attributes re-render the element when they change after the first render.
Properties: items, renderPanel (shortcut only). renderPanel may return a DOM Node or scalar; strings are inserted as text. Emits a bubbling change event with detail.value when the selected tab changes.
Accessibility
Section titled “Accessibility”- WAI-ARIA tabs pattern: roving tabindex, arrow/Home/End navigation, automatic or manual activation.
- In right-to-left text Left and Right swap, so the arrows keep following the reading direction; the page’s
diris read when a key is pressed, with or without a locale provider. - A disabled tab is skipped by the arrow keys and Home/End and is not a tab stop (
tabindex="-1",aria-disabled). - Each panel is correctly wired to its tab (
aria-labelledby/role="tabpanel"), whether it holds textcontentor custom markup. - A tab list holds only tabs. A command such as “add” goes in the actions area, never in
items: there it is an ordinary button, reached with Tab after the selected tab, and the arrow keys never land on it.
Example
Section titled “Example”<Tabs label="Settings" value="account" items={[ { value: "account", label: "Account", content: "Account settings." }, { value: "password", label: "Password", content: "Password settings." }, ]}/>In Elements, assign the item list as a property. Selection is reflected by the
value attribute and reported through the bubbling change event:
<ds-tabs label="Catalog sections"></ds-tabs>
<script type="module"> const tabs = document.querySelector("ds-tabs"); tabs.items = [ { value: "tables", label: "Tables", count: 11, content: "Table list" }, { value: "columns", label: "Columns", count: 42, content: "Column list" }, ]; tabs.addEventListener("change", ({ detail }) => { console.log(detail.value); });</script>In React, content takes any markup, and a count is read as part of the tab’s
name while the badge stays hidden from assistive technology:
<Tabs label="Catalog sections" value={section} onValueChange={setSection} items={[ { value: "tables", label: "Tables", count: 11, content: <TableList /> }, { value: "columns", label: "Columns", count: 42, content: <ColumnList /> }, ]}/>Rich panels
Section titled “Rich panels”For anything beyond text, use the panel snippet: it renders once per tab
with { item }, so you put whatever you want in the (correctly wired) panel and
switch on item.value.
<Tabs label="Inbox" value="all" items={[{ value: "all", label: "All" }, { value: "news", label: "News" }]}> {#snippet panel({ item })} {#if item.value === "all"} <MyList items={everything} /> {:else if item.value === "news"} <MyList items={news} /> {/if} {/snippet}</Tabs>In Elements, set renderPanel to return a DOM node. Strings are always treated
as text rather than parsed as HTML:
tabs.renderPanel = (item) => { const panel = document.createElement("section"); panel.append(item.value === "tables" ? tableView : columnView); return panel;};In React, renderPanel renders a panel from its item:
<Tabs label="Inbox" items={folders} renderPanel={(item) => <MyList folder={item.value} />} />Actions
Section titled “Actions”Commands that act on the tabs, such as “add”, go in the actions area. It sits
right after the tab list, on the same row, outside role="tablist", and wraps
below the tab list when the row is too narrow. Its controls are ordinary
buttons: the tab list keeps its single tab stop, Tab moves from the selected
tab to the actions, and the arrow keys never reach them. Give an icon-only
button a name.
The demo above adds a view and selects it; focus stays on the button, so several views can be added in a row.
<script> let views = $state.raw([{ value: "list", label: "List", content: "List view." }]); let view = $state("list");
function addView() { const number = views.length + 1; const value = `view-${number}`; views = [...views, { value, label: `View ${number}`, content: `View ${number}.` }]; view = value; }</script>
<Tabs label="View" bind:value={view} items={views}> {#snippet actions()} <Button iconOnly variant="ghost" ariaLabel="Add view" onpress={addView}> <Icon><path d="M12 5v14 M5 12h14" /></Icon> </Button> {/snippet}</Tabs>In React, pass the controls as the actions prop:
<Tabs label="View" items={views} value={view} onValueChange={setView} actions={ <Button iconOnly variant="ghost" ariaLabel="Add view" onPress={addView}> <PlusIcon /> </Button> }/>In Vue, use the actions slot:
<Tabs v-model="view" label="View" :items="views"> <template #actions> <Button icon-only variant="ghost" aria-label="Add view" @press="addView"> <PlusIcon /> </Button> </template></Tabs>In Elements, mark the controls slot="actions". The element reads them once,
when it first renders the items shortcut. Composed tabs place such buttons
beside the <ds-tab-list> themselves, as in the example below.
<ds-tabs label="View"> <ds-button slot="actions" icon-only variant="ghost" aria-label="Add view">+</ds-button></ds-tabs>In Flutter, pass the widgets as actions:
iu.Tabs<String>( label: 'View', items: views, value: view, onChanged: (next) => setState(() => view = next), actions: [ iu.Button.icon( onPressed: addView, semanticLabel: 'Add view', icon: const Icon(LucideIcons.plus), ), ],)Composed tabs
Section titled “Composed tabs”When the strip belongs in a header and the panels further down, write the parts
as markup. In Elements, <ds-tabs> is the root that holds the state; inside it,
anywhere, go a <ds-tab-list> of <ds-tab value> elements and one
<ds-tab-panel value> per tab. The tabs wire every part (roles, the links
between tab and panel, which one is visible, the keyboard), so a button placed
beside the strip lines up with the tabs rather than with the panel. The
items form above is the shortcut for the simple case.
<ds-tabs value="form"> <header class="editor-header"> <ds-tab-list label="Editor"> <ds-tab value="form">Form</ds-tab> <ds-tab value="preview">Preview <ds-count count="3"></ds-count></ds-tab> </ds-tab-list> <ds-button variant="ghost">Close</ds-button> </header>
<ds-tab-panel value="form">…</ds-tab-panel> <ds-tab-panel value="preview">…</ds-tab-panel></ds-tabs>In React, the composed form is the useTabs hook: its prop getters wire the
same roles, links, visibility and keys onto markup of your own, wherever it
sits.
const { api } = useTabs({ items: [{ value: "form" }, { value: "preview" }] });
<header className="editor-header"> <div {...api.rootProps} className="tabs__list" aria-label="Editor"> <button {...api.getTabProps("form")} className="tabs__tab">Form</button> <button {...api.getTabProps("preview")} className="tabs__tab">Preview</button> </div> <Button variant="ghost">Close</Button></header><div {...api.getPanelProps("form")} className="tabs__panel">…</div><div {...api.getPanelProps("preview")} className="tabs__panel">…</div>Themeable via --ds-tabs-*.