sveltelean Primitives
Version v0.18.0
Settings
Name, email and avatar.
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>
Click, or Tab into the list and use the arrow keys, Home and End. Under RTL the arrows swap.

Examples

Vertical, manual activation

Vertical tabs
Name, email and avatar.
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>
ArrowDown and ArrowUp move focus; Enter or Space selects.

Application-rendered panel

Orders

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>
With data-slean-render="app" there is one panel and only the selected content exists in the DOM.

Guarded change

Unsaved draft
Name, email and avatar.

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>
A slean:change listener cancels the change; activateTab() goes through the same path.

Counts and a disabled tab

Mail
Twelve unread conversations.
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>
An aria-disabled trigger stays focusable and is skipped by the arrow keys.

Form value

Billing period
€12 per seat, cancel any time.

billing = monthly

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>
The optional native part, a hidden input, carries the selected tab to the form and to bind:value.

Looks

Small, secondary, large and full width
The day report.
The day report.
The day report.
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>
The selected label and its indicator take data-color; data-size sets the height and the text.

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.

With tabsParts()
<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>
Plain markup
<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') writes settings-tab-<value> and settings-panel-<value>, each tab’s aria-controls and each panel’s aria-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) and panel(value, current) write aria-selected, the roving tabindex and hidden from your current value: the attributes the behavior writes on activation, so rendering them from state never fights it.

Points to watch

  • Spread t.list on 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 id and data-slean="tabs" stay in your markup, where @svelte-lean/vite finds 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/primitives
npm install --save-dev @svelte-lean/vite
vite.config.ts
// 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()] });
without the plugin
// 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';
stylesheets
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:

every option
<div
	data-slean="tabs"
	data-slean-value="account"
	data-slean-activation="manual"
	data-slean-orientation="vertical"
	data-slean-loop="false"
	dir="rtl"
>

Anatomy

PartElementdata-slean-partRequiredNotes
root<div data-slean="tabs" data-slean-value="…">–yesdata-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="…">listyesExactly one, with a name. Set aria-orientation="vertical" together with the orientation option.
trigger<button type="button" role="tab" id="…" aria-controls="…">triggeryesOne per tab, with data-slean-value. The selected one has aria-selected="true".
panel<div role="tabpanel" id="…" aria-labelledby="…">panelyesdata-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="…">nativenoCarries 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

KeyWhenResult
Tab/Shift+TabanywhereEnters the tablist on the tabindex="0" trigger (native)
ArrowRight/ArrowLeftfocus on a trigger, horizontalNext or previous enabled trigger; swapped under dir="rtl"
ArrowDown/ArrowUpfocus on a trigger, verticalNext or previous enabled trigger
Home/Endfocus on a triggerFirst or last enabled trigger
Enter/Spacefocus on a triggerSelects 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:

TokenDefault (light)Applies to
--slean-space-1calc(var(--slean-spacing) * 1)gap, padding-block
--slean-bordervar(--slean-neutral-6)box-shadow, border-inline-end
--slean-space-2calc(var(--slean-spacing) * 2)gap, padding-inline
--slean-control-height-md2.25remmin-block-size
--slean-space-3calc(var(--slean-spacing) * 3)padding-inline
--slean-fg-mutedvar(--slean-neutral-11)color
--slean-text-sm0.875remfont-size
--slean-font-weight-medium500font-weight
--slean-duration-fast100mstransition
--slean-easecubic-bezier(0.2, 0, 0, 1)transition
--slean-fgvar(--slean-neutral-12)color
--slean-color-mainvar(--slean-primary-main)border-color, color
--slean-control-height-sm2remmin-block-size
--slean-text-xs0.75remfont-size
--slean-control-height-lg2.75remmin-block-size
--slean-space-4calc(var(--slean-spacing) * 4)padding-inline, padding-block, gap
--slean-text-md1remfont-size
--slean-focus-ring-width2pxoutline-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/primitives/artifacts/size.json · method
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-controls from trigger to panel, aria-labelledby from panel to trigger. Ids are authored, never generated (ADR 0002).
  • State: aria-selected and the roving tabindex on triggers, hidden on panels, data-slean-value on the root. The runtime takes the root's value as current; if the authored aria-selected disagrees, 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 tabindex move 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. A disabled trigger is not focusable; an aria-disabled="true" one is focusable, ignored by click, Enter and Space, and skipped by arrows, Home and End.
  • RTL: direction comes from the nearest dir attribute; 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-orientation that disagrees with the option.
  • With data-slean-render="app": one tabpanel that every trigger's aria-controls names, labelled by the selected trigger; the behavior rewrites aria-labelledby on every change. Validation warns about a panel count other than one, a hidden panel, or a panel labelled by an unselected trigger.
Platform features
FeatureBaselineOutside the target
ARIA tabs roles and states (tablist, tab, tabpanel, aria-selected, aria-controls)ARIA 1.2, widely supported by assistive technologyNot applicable within the support policy
Shared router: composedPath(), getAttribute, ES2022 outputWidely availableNo 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