Primitives Navigation
Tabs
Sections of one page that the reader switches between: ARIA tabs markup, with selection, arrow keys and activation modes handled by a shared behavior. Tier 1.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Code
<script lang="ts">
// @svelte-lean/vite injects the behavior for a static data-slean="tabs" marker.
import '@svelte-lean/styles/tabs.css';
import { tabsParts } from '@svelte-lean/primitives/tabs';
const tabs = [
{ value: 'account', label: 'Account', text: 'Name, email and avatar.' },
{ value: 'security', label: 'Security', text: 'Password, two-factor authentication and sessions.' },
{ value: 'billing', label: 'Billing', text: 'Plan, invoices and payment method.' }
];
// Roles, ids, aria-controls / aria-labelledby, selection and the tab stop, from one id.
const t = tabsParts('settings');
</script>
<div id="settings" data-slean="tabs" data-slean-value="account">
<div {...t.list} aria-label="Settings">
{#each tabs as tab (tab.value)}<button {...t.tab(tab.value, 'account')}>{tab.label}</button>{/each}
</div>
{#each tabs as tab (tab.value)}
<div {...t.panel(tab.value, 'account')} tabindex="0">{tab.text}</div>
{/each}
</div>Examples
Vertical, manual activation
Code
<script lang="ts">
// tabs: the array of the first example
const t = tabsParts('side', { orientation: 'vertical' });
</script>
<div
id="side"
data-slean="tabs"
data-slean-value="account"
data-slean-orientation="vertical"
data-slean-activation="manual"
>
<div {...t.list} aria-label="Settings">
{#each tabs as tab (tab.value)}<button {...t.tab(tab.value, 'account')}>{tab.label}</button>{/each}
</div>
{#each tabs as tab (tab.value)}
<div {...t.panel(tab.value, 'account')} tabindex="0">{tab.text}</div>
{/each}
</div>Application-rendered panel
Three orders wait for packing. The oldest was placed two days ago.
Code
<script lang="ts">
import { on } from 'svelte/events';
import OpenOrders from './OpenOrders.svelte';
import ShippedOrders from './ShippedOrders.svelte';
import ReturnedOrders from './ReturnedOrders.svelte';
const tabs = [
{ value: 'open', label: 'Open' },
{ value: 'shipped', label: 'Shipped' },
{ value: 'returned', label: 'Returned' }
];
// slean:change is dispatched before the behavior writes and may be cancelled, so read the
// root's data-slean-value in a microtask after it.
let value = $state('open');
const follow = (root: HTMLElement) =>
on(root, 'slean:change', () => {
queueMicrotask(() => (value = root.getAttribute('data-slean-value') ?? value));
});
</script>
<div data-slean="tabs" data-slean-value="open" data-slean-render="app" {@attach follow}>
<div role="tablist" aria-label="Orders" data-slean-part="list">
{#each tabs as tab (tab.value)}
<button
type="button"
id="orders-tab-{tab.value}"
role="tab"
aria-controls="orders-panel"
aria-selected={tab.value === value}
tabindex={tab.value === value ? 0 : -1}
data-slean-part="trigger"
data-slean-value={tab.value}
>
{tab.label}
</button>
{/each}
</div>
<!-- Every trigger controls this one panel; the behavior points aria-labelledby at the selected one. -->
<div
id="orders-panel"
role="tabpanel"
aria-labelledby="orders-tab-open"
data-slean-part="panel"
tabindex="0"
>
{#if value === 'open'}
<OpenOrders />
{:else if value === 'shipped'}
<ShippedOrders />
{:else}
<ReturnedOrders />
{/if}
</div>
</div>Guarded change
No change yet.
Code
<script lang="ts">
import { on } from 'svelte/events';
import { activateTab, type TabsChangeDetail } from '@svelte-lean/primitives/tabs';
import '@svelte-lean/styles/button.css';
import '@svelte-lean/styles/checkbox.css';
let root: HTMLElement;
let unsaved = $state(false);
let status = $state('No change yet.');
// slean:change bubbles from the root before the DOM is written; preventDefault() keeps
// the current tab.
const guard = (node: HTMLElement) =>
on(node, 'slean:change', (event) => {
const { value, previous } = (event as CustomEvent<TabsChangeDetail>).detail;
if (unsaved) {
event.preventDefault();
status = `Stayed on ${previous}: the draft is not saved.`;
} else {
status = `${previous} → ${value}`;
}
});
</script>
<div data-slean="tabs" data-slean-value="account" bind:this={root} {@attach guard}>
<!-- the list and panels of the settings tabs -->
</div>
<label>
<input type="checkbox" data-slean="checkbox" bind:checked={unsaved} />
Unsaved draft
</label>
<button type="button" data-slean="button" data-variant="outlined" data-color="neutral" data-size="small"
onclick={() => activateTab(root, 'billing')}>
Open billing
</button>
<p role="status">{status}</p>Counts and a disabled tab
Code
<script lang="ts">
import '@svelte-lean/styles/badge.css';
const tabs = [
{ value: 'inbox', label: 'Inbox', count: 12 },
{ value: 'drafts', label: 'Drafts', count: 3 },
{ value: 'archive', label: 'Archive', disabled: true }
];
</script>
<div data-slean="tabs" data-slean-value="inbox">
<div role="tablist" aria-label="Mail" data-slean-part="list">
{#each tabs as tab, i (tab.value)}
<button
type="button"
id="mail-tab-{tab.value}"
role="tab"
aria-controls="mail-panel-{tab.value}"
aria-selected={i === 0}
aria-disabled={tab.disabled ? 'true' : undefined}
tabindex={i === 0 ? 0 : -1}
data-slean-part="trigger"
data-slean-value={tab.value}
>
{tab.label}
{#if tab.count}<span data-slean="badge" data-size="small">{tab.count}</span>{/if}
</button>
{/each}
</div>
<!-- one panel per tab, as in the settings example -->
</div>Form value
Code
<script lang="ts">
import { tabsParts } from '@svelte-lean/primitives/tabs';
const periods = [
{ value: 'monthly', label: 'Monthly', text: '€12 per seat, cancel any time.' },
{ value: 'yearly', label: 'Yearly', text: '€120 per seat, two months free.' }
];
const t = tabsParts('period');
// One state renders the root, the triggers, the panels and the hidden input; the behavior
// writes the input on every change and dispatches input, so bind:value follows.
let period = $state('monthly');
</script>
<form method="post">
<div id="period" data-slean="tabs" data-slean-value={period}>
<input {...t.native} name="billing" bind:value={period} />
<div {...t.list} aria-label="Billing period">
{#each periods as p (p.value)}<button {...t.tab(p.value, period)}>{p.label}</button>{/each}
</div>
{#each periods as p (p.value)}
<div {...t.panel(p.value, period)} tabindex="0">{p.text}</div>
{/each}
</div>
<p>billing = {period}</p>
<button type="submit" data-slean="button">Continue</button>
</form>Looks
Code
<!-- data-size: small | medium (default) | large; data-color: primary (default) and the palette;
data-full-width: the triggers share the list's width. -->
<div id="small" data-slean="tabs" data-slean-value="day" data-size="small">…</div>
<div id="colored" data-slean="tabs" data-slean-value="day" data-color="secondary">…</div>
<div id="wide" data-slean="tabs" data-slean-value="day" data-size="large" data-full-width>…</div>Helper or plain markup
Two ways to write the same markup: with tabsParts() or by hand. Both render the same
HTML, which a test of this site compares; use either.
<script lang="ts">
import { tabsParts } from '@svelte-lean/primitives/tabs';
const t = tabsParts('settings');
const tabs = [
{
value: 'account',
label: 'Account',
body: 'Name and email.'
},
{
value: 'billing',
label: 'Billing',
body: 'Plan and invoices.'
}
];
const current = 'account';
</script>
<div id="settings" data-slean="tabs" data-slean-value={current}>
<div {...t.list} aria-label="Settings">
{#each tabs as tab (tab.value)}
<button {...t.tab(tab.value, current)}>{tab.label}</button
>
{/each}
</div>
{#each tabs as tab (tab.value)}
<div {...t.panel(tab.value, current)}>{tab.body}</div>
{/each}
</div><div id="settings" data-slean="tabs" data-slean-value="account">
<div
role="tablist"
aria-label="Settings"
data-slean-part="list"
>
<button
type="button"
id="settings-tab-account"
role="tab"
aria-controls="settings-panel-account"
aria-selected="true"
tabindex="0"
data-slean-part="trigger"
data-slean-value="account"
>
Account
</button>
<button
type="button"
id="settings-tab-billing"
role="tab"
aria-controls="settings-panel-billing"
aria-selected="false"
tabindex="-1"
data-slean-part="trigger"
data-slean-value="billing"
>
Billing
</button>
</div>
<div
id="settings-panel-account"
role="tabpanel"
aria-labelledby="settings-tab-account"
data-slean-part="panel"
data-slean-value="account"
>
Name and email.
</div>
<div
id="settings-panel-billing"
role="tabpanel"
aria-labelledby="settings-tab-billing"
data-slean-part="panel"
data-slean-value="billing"
hidden
>
Plan and invoices.
</div>
</div>What the helper does
- One id in, every part id out:
tabsParts('settings')writessettings-tab-<value>andsettings-panel-<value>, each tab’saria-controlsand each panel’saria-labelledby. - Strings only: no handler, no state, no instance. The server and the browser render the same attributes, so hydration has nothing to patch.
tab(value, current)andpanel(value, current)writearia-selected, the rovingtabindexandhiddenfrom your current value: the attributes the behavior writes on activation, so rendering them from state never fights it.
Points to watch
- Spread
t.liston the tab list and name it yourself (aria-label);t.tab()goes on each<button>,t.panel()on each panel. - It registers nothing and imports no stylesheet: the root's
idanddata-slean="tabs"stay in your markup, where@svelte-lean/vitefinds them. - Values are used in ids, so a value must not contain whitespace.
- Ids must be unique on the page. Hand-written markup works the same; the ids and the references between them are then yours to keep in step.
Usage
Install @svelte-lean/primitives, @svelte-lean/styles and the Vite
plugin. The plugin adds the register import to every Svelte file with a static data-slean="tabs"; without it, or with a dynamic marker, import the register module
once yourself.
npm install @svelte-lean/primitivespnpm add @svelte-lean/primitivesyarn add @svelte-lean/primitivesbun add @svelte-lean/primitivesnpm install --save-dev @svelte-lean/vitepnpm add -D @svelte-lean/viteyarn add -D @svelte-lean/vitebun add -d @svelte-lean/vite// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';
export default defineConfig({ plugins: [svelteLean(), sveltekit()] });// Any module that runs once on the client, for example the root layout. Safe on the server,
// idempotent, and the same module the plugin injects.
import '@svelte-lean/primitives/tabs/register';import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '@svelte-lean/styles/tabs.css';Use tabs for sections of one page; sections that are separate pages are links in a <nav>. Every option is an attribute on the root:
<div
data-slean="tabs"
data-slean-value="account"
data-slean-activation="manual"
data-slean-orientation="vertical"
data-slean-loop="false"
dir="rtl"
>Anatomy
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <div data-slean="tabs" data-slean-value="…"> | – | yes | data-slean-value names the selected tab. Options: data-slean-activation, data-slean-orientation, data-slean-loop, data-slean-render="app". Looks: data-size, data-color, data-full-width. |
| list | <div role="tablist" aria-label="…"> | list | yes | Exactly one, with a name. Set aria-orientation="vertical" together with the orientation option. |
| trigger | <button type="button" role="tab" id="…" aria-controls="…"> | trigger | yes | One per tab, with data-slean-value. The selected one has aria-selected="true". |
| panel | <div role="tabpanel" id="…" aria-labelledby="…"> | panel | yes | data-slean-value matching a trigger; hidden when not selected. With data-slean-render="app": exactly one, controlled by every trigger, content rendered by the application. Add tabindex="0" when it has no focusable content. |
| native | <input type="hidden" name="…"> | native | no | Carries the selected value to a form and to bind:value: written (with input and change events) on every change, never read. |
Parts inside a nested tabs root belong to the nested root only; inner interactions never change the outer root.
Keyboard
| Key | When | Result |
|---|---|---|
| Tab/Shift+Tab | anywhere | Enters the tablist on the tabindex="0" trigger (native) |
| ArrowRight/ArrowLeft | focus on a trigger, horizontal | Next or previous enabled trigger; swapped under dir="rtl" |
| ArrowDown/ArrowUp | focus on a trigger, vertical | Next or previous enabled trigger |
| Home/End | focus on a trigger | First or last enabled trigger |
| Enter/Space | focus on a trigger | Selects the focused trigger (required in manual mode) |
In automatic mode a move also selects. Keys with Alt, Ctrl or Meta are ignored, so browser
shortcuts keep working. With data-slean-loop="false" the ends stop instead of wrapping.
Styling
tabs.css styles the list, triggers and panels through their parts; the indicator is
the trigger's border, colored on [aria-selected="true"]. The vertical orientation
moves the list to the inline-start side. The tokens it reads and the states it targets:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-1 | calc(var(--slean-spacing) * 1) | gap, padding-block |
--slean-border | var(--slean-neutral-6) | box-shadow, border-inline-end |
--slean-space-2 | calc(var(--slean-spacing) * 2) | gap, padding-inline |
--slean-control-height-md | 2.25rem | min-block-size |
--slean-space-3 | calc(var(--slean-spacing) * 3) | padding-inline |
--slean-fg-muted | var(--slean-neutral-11) | color |
--slean-text-sm | 0.875rem | font-size |
--slean-font-weight-medium | 500 | font-weight |
--slean-duration-fast | 100ms | transition |
--slean-ease | cubic-bezier(0.2, 0, 0, 1) | transition |
--slean-fg | var(--slean-neutral-12) | color |
--slean-color-main | var(--slean-primary-main) | border-color, color |
--slean-control-height-sm | 2rem | min-block-size |
--slean-text-xs | 0.75rem | font-size |
--slean-control-height-lg | 2.75rem | min-block-size |
--slean-space-4 | calc(var(--slean-spacing) * 4) | padding-inline, padding-block, gap |
--slean-text-md | 1rem | font-size |
--slean-focus-ring-width | 2px | outline-offset |
State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :focus-visible, :hover, [aria-disabled="true"], [aria-selected="true"].
Variant attributes: data-size (small, large); data-full-width; data-slean-orientation (vertical).
Controlled integration
The root dispatches a bubbling, cancelable slean:change before the DOM is written,
with detail of type TabsChangeDetail (value, previous); preventDefault() cancels the selection. activateTab(root, value) from @svelte-lean/primitives/tabs selects
through the same path and returns false when cancelled. The guarded change example uses both.
Note A Svelte adapter that binds the selected value is not built. Selection lives in data-slean-value: read it from the root or the event, write it with activateTab().
Under the hood
Runtime and size
- Tier
- 1 · Delegated micro-behavior
- Behavior JS
- 1839 B brotli · 2048 B gzip ·
packages/· methodprimitives/ artifacts/ size.json - Platform features
role="tablist",role="tab",aria-selected,roving tabindex,hidden- Shared listeners
- click, keydown
- Per-instance listeners
- none
- Lazy state
- none
- Native base
ARIA tabs markup (role=tablist, tab, tabpanel)
The bytes are the production build of @svelte-lean/primitives/tabs/register including the shared kernel, from packages/primitives/artifacts/size.json (1839 B brotli · 2048 B gzip). Plugin and manual
registration ship the same modules: the manual-registration fixture builds to a
Svelte Lean chunk of 1839 B brotli, the tabs-only fixture with the plugin to 1839 B brotli.
The release gate of ADR 0004: 1000 roots on one page keep the runtime's account at one click and one keydown listener, counted by the runtime and by an
independent wrapper around addEventListener. The proof page repeats that reading in your browser.
Nothing runs at hydration: no scan of the document, no per-root setup. The first event on a
root is the first work done for it; development builds validate the markup once then. There
is no WeakMap, observer or layout read in the behavior source. Time from
navigation to a page with 1000 interactive roots: 68.6 ms (median of 5 loads, chromium 153.0.8010.12, AMD EPYC 9555P 64-Core Processor,
2026-10-05T07:11:03.593Z).
Why this implementation
The browser has no tabs element. The ARIA pattern needs a roving tabindex,
arrow keys, Home and End, automatic or manual activation, and panels that follow the
selection. Svelte Lean adds that and nothing around it: no component, no per-instance
listener, no mirrored state. The shared router in @svelte-lean/core walks composedPath() to the nearest data-slean="tabs" root, and the handler
reads and writes attributes (ADR 0004).
The browser owns
- the tab order: Tab enters the list on the trigger with tabindex="0"
- the tab, tablist and tabpanel roles and their announcements
- the click and keydown events routed to the behavior
- hiding panels through the hidden attribute
Svelte Lean owns
- selection on click, Enter and Space; arrow keys, Home and End; automatic and manual activation
- writing aria-selected, the roving tabindex, hidden and data-slean-value (with data-slean-render="app", the one panel's aria-labelledby instead of hidden)
- the cancelable slean:change event and activateTab()
- development validation of the markup
- tabs.css and the contract
Accessibility
- Roles:
tablist(named),tab,tabpanel.aria-controlsfrom trigger to panel,aria-labelledbyfrom panel to trigger. Ids are authored, never generated (ADR 0002). - State:
aria-selectedand the rovingtabindexon triggers,hiddenon panels,data-slean-valueon the root. The runtime takes the root's value as current; if the authoredaria-selecteddisagrees, the first activation corrects it and development builds warn. - Focus: a click focuses the trigger (Safari does not by itself). In manual mode focus and
tabindexmove while the selection waits for Enter or Space. When a listener cancels a change, selection stays and keyboard focus still moves. - Disabled:
aria-disabled="true"on the root makes the router skip it. Adisabledtrigger is not focusable; anaria-disabled="true"one is focusable, ignored by click, Enter and Space, and skipped by arrows, Home and End. - RTL: direction comes from the nearest
dirattribute;dir="auto"is resolved through:dir(rtl). Computed style is never read. - Development validation warns about a missing or duplicated list, duplicate values,
triggers without panels and panels without triggers, missing roles or relationships, a
root value that matches no trigger, and an
aria-orientationthat disagrees with the option. - With
data-slean-render="app": onetabpanelthat every trigger'saria-controlsnames, labelled by the selected trigger; the behavior rewritesaria-labelledbyon every change. Validation warns about a panel count other than one, ahiddenpanel, or a panel labelled by an unselected trigger.
Platform features
| Feature | Baseline | Outside the target |
|---|---|---|
ARIA tabs roles and states (tablist, tab, tabpanel, aria-selected, aria-controls) | ARIA 1.2, widely supported by assistive technology | Not applicable within the support policy |
Shared router: composedPath(), getAttribute, ES2022 output | Widely available | No transpilation to an older target is provided |
:dir(rtl), only to resolve dir="auto" | Newly available since December 2023 (Chrome 120, Safari 16.4, Firefox 49) | Guarded in packages/primitives/src/internal/direction.ts: dir="auto" resolves to left-to-right; explicit dir attributes work everywhere |
Without JavaScript
The authored state stays: the selected panel is visible, the others are hidden, and
switching is impossible; the delayed-hydration test asserts it. Pages that must work without
script can render the panels without hidden as a stacked layout, or link between
pages.
Server rendering and hydration
The server renders the selected state as authored, with authored ids. The register module is
safe to import on the server; without a document it waits for a browser runtime
(packages/primitives/tests/ssr.test.ts). The playground's SSR spec finds aria-selected, tabindex, hidden and the root value as authored.
The register module evaluates before the component code and installs the two listeners. A click before it has loaded changes nothing; after hydration the delayed-hydration test presses ArrowRight and sees the selection move.
Compatibility
The behavior needs the ES2022 output the packages emit and composedPath(). :dir() only resolves dir="auto" and is guarded: where it is
unsupported, dir="auto" resolves to left-to-right. The behavior is tested in
Chromium; Firefox and WebKit runs do not exist yet. The policy is on Browser support.
Tests and source
packages/primitives/tests/tabs.test.tsunit tests (happy-dom): click, arrows, Home/End, activation modes, disabled, RTL, nesting, cancellation, 1000 rootsapps/playground/tests/primitives/tabs.spec.tsPlaywright: real focus movement, :focus-visible, RTL, slean:change, a Svelte page that renders only the selected panelapps/playground/tests/primitives/listeners.spec.ts1 root against 1000 roots: the listener count is the release gateapps/playground/tests/primitives/nested.spec.tstabs inside a menu, a menu inside a panel, tabs inside a modal dialogapps/playground/tests/bench/tabs.bench.spec.tsstartup and interaction timings of 1000 roots, written to bench.jsonfixtures/tabs-only and fixtures/manual-registrationconsumer builds: only the tabs registration ships; the manual import ships the same modulesapps/playground/tests/primitives/a11y.spec.tsaxe on every playground page and on open dialog, popover and menu states
packages/primitives/src/tabs/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/tabs/contract.tstyped constants: name, tier, base, parts, options, eventspackages/primitives/src/tabs/behavior.tsthe behavior definition and activateTab()packages/primitives/src/tabs/register.tsthe registration module, the only side effectpackages/primitives/src/tabs/validate.tsdevelopment validation messagespackages/styles/css/tabs.cssthe optional stylesheet