Skip to content

Tabs

Manage your account settings.
Change your password here.
Invite and manage team members.
Every message.
Messages you haven't read.
Archived messages.
List view.
Grid view.

A WAI-ARIA tabs widget: a tablist linked to panels, with arrow navigation.

<script>
import Tabs from "@invisible-ui/svelte/Tabs.svelte";
</script>
PropTypeDefaultDescription
items *TabsItem[]—
valuestring | nullnull
activationModeActivationMode"automatic"
label *string—Accessible name for the tab list.
onValueChange((value: string) => void) | undefinedundefinedCalled whenever the selected tab changes.
panelSnippet<[{ item: TabsItem }]> | undefinedundefinedRich content of one panel, rendered once per tab with its item.
actionsSnippet | undefinedundefinedCommands beside the tab list, outside it, such as an "add" button.
  • 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 dir is 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 text content or 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.
<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 /> },
]}
/>

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} />} />

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),
),
],
)

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-*.