Tabs

Example

<div 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-security"
			role="tab"
			aria-controls="settings-panel-security"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="security"
		>
			Security
		</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"
		tabindex="0"
	>
		Name, email and avatar.
	</div>
	<div
		id="settings-panel-security"
		role="tabpanel"
		aria-labelledby="settings-tab-security"
		data-slean-part="panel"
		data-slean-value="security"
		tabindex="0"
		hidden
	>
		Password, two-factor authentication and sessions.
	</div>
	<div
		id="settings-panel-billing"
		role="tabpanel"
		aria-labelledby="settings-tab-billing"
		data-slean-part="panel"
		data-slean-value="billing"
		tabindex="0"
		hidden
	>
		Plan, invoices and payment method.
	</div>
</div>

<script lang="ts">
	// With @svelte-lean/vite this import is injected for the static data-slean="tabs" marker.
	// Without the plugin, write it yourself once; both paths register the same behavior.
	import '@svelte-lean/primitives/tabs/register';
	import '@svelte-lean/styles/tabs.css';
</script>

<div 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-security"
			role="tab"
			aria-controls="settings-panel-security"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="security"
		>
			Security
		</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"
		tabindex="0"
	>
		Name, email and avatar.
	</div>
	<div
		id="settings-panel-security"
		role="tabpanel"
		aria-labelledby="settings-tab-security"
		data-slean-part="panel"
		data-slean-value="security"
		tabindex="0"
		hidden
	>
		Password, two-factor authentication and sessions.
	</div>
	<div
		id="settings-panel-billing"
		role="tabpanel"
		aria-labelledby="settings-tab-billing"
		data-slean-part="panel"
		data-slean-value="billing"
		tabindex="0"
		hidden
	>
		Plan, invoices and payment method.
	</div>
</div>

Last slean:change on the example: No change yet.

Vertical orientation, manual activation

<div
	data-slean="tabs"
	data-slean-value="account"
	data-slean-orientation="vertical"
	data-slean-activation="manual"
>
	<div role="tablist" aria-label="Settings" aria-orientation="vertical" data-slean-part="list">
		<button
			type="button"
			id="side-tab-account"
			role="tab"
			aria-controls="side-panel-account"
			aria-selected="true"
			tabindex="0"
			data-slean-part="trigger"
			data-slean-value="account"
		>
			Account
		</button>
		<button
			type="button"
			id="side-tab-security"
			role="tab"
			aria-controls="side-panel-security"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="security"
		>
			Security
		</button>
		<button
			type="button"
			id="side-tab-billing"
			role="tab"
			aria-controls="side-panel-billing"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="billing"
		>
			Billing
		</button>
	</div>
	<div
		id="side-panel-account"
		role="tabpanel"
		aria-labelledby="side-tab-account"
		data-slean-part="panel"
		data-slean-value="account"
		tabindex="0"
	>
		Name, email and avatar.
	</div>
	<div
		id="side-panel-security"
		role="tabpanel"
		aria-labelledby="side-tab-security"
		data-slean-part="panel"
		data-slean-value="security"
		tabindex="0"
		hidden
	>
		Password, two-factor authentication and sessions.
	</div>
	<div
		id="side-panel-billing"
		role="tabpanel"
		aria-labelledby="side-tab-billing"
		data-slean-part="panel"
		data-slean-value="billing"
		tabindex="0"
		hidden
	>
		Plan, invoices and payment method.
	</div>
</div>

<script lang="ts">
	import '@svelte-lean/primitives/tabs/register';
	import '@svelte-lean/styles/tabs.css';
</script>

<div
	data-slean="tabs"
	data-slean-value="account"
	data-slean-orientation="vertical"
	data-slean-activation="manual"
>
	<div role="tablist" aria-label="Settings" aria-orientation="vertical" data-slean-part="list">
		<button
			type="button"
			id="side-tab-account"
			role="tab"
			aria-controls="side-panel-account"
			aria-selected="true"
			tabindex="0"
			data-slean-part="trigger"
			data-slean-value="account"
		>
			Account
		</button>
		<button
			type="button"
			id="side-tab-security"
			role="tab"
			aria-controls="side-panel-security"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="security"
		>
			Security
		</button>
		<button
			type="button"
			id="side-tab-billing"
			role="tab"
			aria-controls="side-panel-billing"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="billing"
		>
			Billing
		</button>
	</div>
	<div
		id="side-panel-account"
		role="tabpanel"
		aria-labelledby="side-tab-account"
		data-slean-part="panel"
		data-slean-value="account"
		tabindex="0"
	>
		Name, email and avatar.
	</div>
	<div
		id="side-panel-security"
		role="tabpanel"
		aria-labelledby="side-tab-security"
		data-slean-part="panel"
		data-slean-value="security"
		tabindex="0"
		hidden
	>
		Password, two-factor authentication and sessions.
	</div>
	<div
		id="side-panel-billing"
		role="tabpanel"
		aria-labelledby="side-tab-billing"
		data-slean-part="panel"
		data-slean-value="billing"
		tabindex="0"
		hidden
	>
		Plan, invoices and payment method.
	</div>
</div>

Why this implementation exists

The browser has no tabs element. The ARIA pattern needs a roving tabindex, arrow keys that move between triggers, Home and End, a choice between automatic and manual activation, and panels that hide and show with the selection. That is behavior the platform does not provide, so Svelte Lean adds exactly that and nothing around it: no component, no per-instance listener, no mirrored state. The behavior is registered once per page; 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).

Usage

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

npm install --save-dev @svelte-lean/vite

pnpm add -D @svelte-lean/vite

yarn add -D @svelte-lean/vite

bun add -d @svelte-lean/vite

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

With the Vite plugin, every static data-slean="tabs" in a Svelte file gets import '@svelte-lean/primitives/tabs/register' appended to its compiled module. Without the plugin, with a dynamic marker (data-slean={name}) or in a build that is not Vite, write that import yourself once. Both paths ship the same modules: the manual-registration fixture builds to a Svelte Lean chunk of 1521 B brotli, the tabs-only fixture with the plugin to 1521 B brotli.

// 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 that the reader switches between without navigating. Sections that are separate pages are links in a <nav>, not tabs. The options are attributes on the root, one per option:

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

Anatomy

Parts inside a nested tabs root belong to the nested root only; the handlers check closestRoot() before acting, and the nested test suite proves that inner interactions never change the outer root.

Runtime profile

The bytes in the runtime block are the production build of @svelte-lean/primitives/tabs/register including the shared kernel, from packages/primitives/artifacts/size.json (1521 B brotli · 1693 B gzip); the file also records the enforced budget, and the esbuild figure kept for comparison. The listeners are the release gate of ADR 0004: 1000 roots on one page keep the runtime's account at one click and one keydown, counted by the runtime and by an independent wrapper around addEventListener, and the last root is interactive by pointer and keyboard. 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, and development builds validate the markup once on that event. There is no WeakMap, no observer and no layout read in the behavior source (asserted by the unit tests). The playground's bench project records the time from navigation to a page with 1000 roots being interactive: 98.8 ms (median of 5 loads, chromium 153.0.8010.53, Apple M2, 2026-09-27T20:46:17.407Z).

Accessibility contract

• Roles: tablist on the list (with a name), tab on every trigger, tabpanel on every panel. Relationships: aria-controls from trigger to panel id, aria-labelledby from panel to trigger id. 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 DOM is the state; the runtime takes the root's value as current and never scans aria-selected. If the authored aria-selected disagrees with the root value, the first activation corrects it and development builds warn.
• Focus: roving tabindex. A click focuses the trigger (Safari does not focus buttons on click by itself). In manual mode focus and tabindex move while the selection stays until Enter or Space. When a slean:change listener cancels, selection and tabindex stay; keyboard focus still moves.
• Disabled: data-slean-disabled or aria-disabled="true" on the root makes the router skip it. A trigger with disabled is not focusable; with aria-disabled="true" it is focusable, ignored by click, Enter and Space, and skipped by arrows, Home and End.
• RTL: direction is read from the nearest dir attribute; dir="auto" is resolved through :dir(rtl). Computed style is never read.
• Development validation warns about: not exactly one list, a list without role="tablist", duplicate trigger values, triggers without a panel and panels without a trigger, missing roles or relationships, a root without a value or with a value that matches no trigger, and an aria-orientation that disagrees with the option.

Keyboard

In automatic mode a move also selects. Keys with Alt, Ctrl or Meta are ignored so browser shortcuts keep working; handled keys call preventDefault(). With data-slean-loop="false" the ends stop instead of wrapping and the key is still consumed.

Platform features

Without JavaScript

The authored state stays: the selected panel is visible, the others are hidden, and switching is impossible. This is asserted, not hidden: the delayed-hydration test clicks a trigger before any script has loaded and checks that nothing changed. Pages that must work without script can render the panels without hidden and accept a stacked layout, or link between pages.

Server rendering

Everything is static markup: the server renders the selected state exactly as authored, with authored ids. The register module is safe to import on the server; without a document the registration waits until a browser runtime exists (packages/primitives/tests/ssr.test.ts). The playground's SSR spec reads the server HTML and finds aria-selected, tabindex, hidden and the root value as authored.

Before hydration

The register module is an ES module import, so it evaluates before the component code and installs the two listeners when the first behavior registers. A click that arrives before that module has loaded changes nothing, which the delayed-hydration test asserts. When the scripts arrive, hydration leaves the authored state untouched and the behavior is live: the same test then presses ArrowRight and sees the selection move.

Styling

tabs.css styles the list, the triggers and the 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:

State selectors the stylesheet targets, all from the platform or ARIA: :disabled, :focus-visible, :hover, [aria-disabled="true"], [aria-selected="true"].

Variant attributes: data-slean-orientation (vertical).

Controlled integration

What exists today: the root dispatches a bubbling, cancelable slean:change CustomEvent 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 programmatically through the same path and returns false when cancelled. An application listens with addEventListener, as the status line under the example does.

<script lang="ts">
	import { activateTab, type TabsChangeDetail } from '@svelte-lean/primitives/tabs';

	let root: HTMLElement;
	let subscribed = $state(false);

	$effect(() => {
		// slean:change bubbles from the root before the DOM is written; preventDefault() keeps
		// the current tab. The selected value stays in data-slean-value, not in a store.
		const onChange = (event: Event) => {
			const { value, previous } = (event as CustomEvent<TabsChangeDetail>).detail;
			if (value === 'billing' && !subscribed) event.preventDefault();
			console.log(previous, '->', value);
		};
		root.addEventListener('slean:change', onChange);
		return () => root.removeEventListener('slean:change', onChange);
	});

	// Programmatic selection goes through the same path and returns false when cancelled.
	const showBilling = () => activateTab(root, 'billing');
</script>

<div data-slean="tabs" data-slean-value="account" bind:this={root}>…</div>

Compatibility notes

The behavior needs the ES2022 output the packages emit and the shared router's composedPath(); no transpilation to an older target is provided. :dir() is used only to resolve dir="auto" and is guarded, so where it is unsupported dir="auto" resolves to left-to-right and explicit dir attributes work everywhere. The behavior is tested in Chromium; Firefox and WebKit runs do not exist yet. The policy is on Browser support.

Testing

• packages/primitives/tests/tabs.test.ts unit tests (happy-dom): click, arrows, Home/End, activation modes, disabled, RTL, nesting, cancellation, 1000 roots
• apps/playground/tests/primitives/tabs.spec.ts Playwright: real focus movement, :focus-visible, RTL, slean:change
• apps/playground/tests/primitives/listeners.spec.ts 1 root against 1000 roots: the listener count is the release gate
• apps/playground/tests/primitives/nested.spec.ts tabs inside a menu, a menu inside a panel, tabs inside a modal dialog
• apps/playground/tests/bench/tabs.bench.spec.ts startup and interaction timings of 1000 roots, written to bench.json
• fixtures/tabs-only and fixtures/manual-registration consumer builds: only the tabs registration ships; the manual import ships the same modules
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states

Source

• packages/primitives/src/tabs/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/tabs/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/tabs/behavior.ts the behavior definition and activateTab()
• packages/primitives/src/tabs/register.ts the registration module, the only side effect
• packages/primitives/src/tabs/validate.ts development validation messages
• packages/styles/css/tabs.css the optional stylesheet