sveltelean Primitives
Version v0.18.0
Single select
  • Apple
  • Banana
  • Cherry
  • Date
  • Elderberry

Selected: Apple

Code
<script lang="ts">
	// With @svelte-lean/vite the behavior registers itself for data-slean="listbox".
	import '@svelte-lean/styles/listbox.css';
	import type { ListboxChangeDetail } from '@svelte-lean/primitives/listbox';
	import { on } from 'svelte/events';

	const fruits = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
	let fruit = $state('Apple');

	function onFruit(event: Event) {
		fruit = String((event as CustomEvent<ListboxChangeDetail>).detail.value);
	}
</script>

<ul
	role="listbox"
	aria-label="Fruit"
	data-slean="listbox"
	class="fruit"
	{@attach (node) => on(node, 'slean:change', onFruit)}
>
	{#each fruits as option (option)}
		<li
			role="option"
			aria-selected={option === fruit}
			tabindex={option === fruit ? 0 : -1}
			data-slean-value={option}
		>
			{option}
		</li>
	{/each}
</ul>
<p>Selected: {fruit}</p>

<style>
	.fruit {
		max-inline-size: 16rem;
	}
</style>
Tab enters on the selected option; the arrows select as they move, Home and End jump, a letter searches.

Examples

Multi-select

Multi-select
  • Cheese
  • Olives
  • Peppers
  • Mushrooms
  • Basil

2 selected: Cheese, Basil

Code
<script lang="ts">
	import '@svelte-lean/styles/listbox.css';
	import type { ListboxChangeDetail } from '@svelte-lean/primitives/listbox';
	import { on } from 'svelte/events';

	const toppings = ['Cheese', 'Olives', 'Peppers', 'Mushrooms', 'Basil'];
	let chosen = $state(['Cheese', 'Basil']);

	function onToppings(event: Event) {
		const { value } = (event as CustomEvent<ListboxChangeDetail>).detail;
		chosen = Array.isArray(value) ? value : [];
	}
</script>

<ul
	role="listbox"
	aria-label="Toppings"
	aria-multiselectable="true"
	data-slean="listbox"
	data-slean-multiple
	class="toppings"
	{@attach (node) => on(node, 'slean:change', onToppings)}
>
	{#each toppings as option, i (option)}
		<li
			role="option"
			aria-selected={chosen.includes(option)}
			tabindex={i === 0 ? 0 : -1}
			data-slean-value={option}
		>
			{option}
		</li>
	{/each}
</ul>
<p>{chosen.length} selected: {chosen.join(', ') || 'none'}</p>

<style>
	.toppings {
		max-inline-size: 16rem;
	}
</style>
Arrows move focus only; Space, Enter or a click toggles, Shift+Arrow extends, Ctrl+A (Cmd+A) selects every enabled option.

Multi-select in a popover

Multi-select in a popover
  • Open
  • In review
  • Done
  • Archived
Code
<script lang="ts">
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/popover.css';
	import '@svelte-lean/styles/listbox.css';
	import type { ListboxChangeDetail } from '@svelte-lean/primitives/listbox';
	import { on } from 'svelte/events';

	const statuses = ['Open', 'In review', 'Done', 'Archived'];
	let filter = $state(['Open', 'In review']);
	const summary = $derived(
		filter.length === 0 ? 'Any' : filter.length === 1 ? filter[0] : `${filter.length} selected`
	);

	function onStatus(event: Event) {
		const { value } = (event as CustomEvent<ListboxChangeDetail>).detail;
		filter = Array.isArray(value) ? value : [];
	}
</script>

<button
	type="button"
	data-slean="button"
	data-variant="outlined"
	data-color="neutral"
	popovertarget="status-filter"
	aria-haspopup="listbox"
>
	Status: {summary}
</button>
<div
	id="status-filter"
	popover
	data-slean="popover"
	data-slean-align="start"
	class="filter"
>
	<ul
		role="listbox"
		aria-label="Status"
		aria-multiselectable="true"
		data-slean="listbox"
		data-slean-multiple
		{@attach (node) => on(node, 'slean:change', onStatus)}
	>
		{#each statuses as option, i (option)}
			<li
				role="option"
				aria-selected={filter.includes(option)}
				tabindex={i === 0 ? 0 : -1}
				data-slean-value={option}
			>
				{option}
			</li>
		{/each}
	</ul>
</div>

<style>
	/* One surface: the popover's, with the list inside it unframed. */
	.filter {
		padding: 0.25rem;
	}

	.filter [role='listbox'] {
		border: 0;
		padding: 0;
	}
</style>
The popover owns showing, light dismiss and focus return; the listbox owns the keys; the button label follows slean:change.

Rich options

Rich options
  • Ada Okafor Design
  • Lin Chen Engineering
  • Sam Rivera Away until Monday
  • Noor Haddad Support
Code
<script lang="ts">
	import '@svelte-lean/styles/avatar.css';
	import '@svelte-lean/styles/listbox.css';
	import type { ListboxChangeDetail } from '@svelte-lean/primitives/listbox';
	import { on } from 'svelte/events';

	const people = [
		{ id: 'ada', name: 'Ada Okafor', team: 'Design', initials: 'AO' },
		{ id: 'lin', name: 'Lin Chen', team: 'Engineering', initials: 'LC' },
		{ id: 'sam', name: 'Sam Rivera', team: 'Away until Monday', initials: 'SR', away: true },
		{ id: 'noor', name: 'Noor Haddad', team: 'Support', initials: 'NH' }
	];
	let assignee = $state('lin');

	function onAssignee(event: Event) {
		assignee = String((event as CustomEvent<ListboxChangeDetail>).detail.value);
	}
</script>

<ul
	role="listbox"
	aria-label="Assignee"
	data-slean="listbox"
	class="people"
	{@attach (node) => on(node, 'slean:change', onAssignee)}
>
	{#each people as person (person.id)}
		<li
			role="option"
			aria-selected={person.id === assignee}
			aria-disabled={person.away || undefined}
			tabindex={person.id === assignee ? 0 : -1}
			data-slean-value={person.id}
		>
			<span data-slean="avatar" data-size="small">
				<span data-slean-part="fallback" aria-hidden="true">{person.initials}</span>
			</span>
			<span class="person">
				{person.name}
				<small>{person.team}</small>
			</span>
		</li>
	{/each}
</ul>

<style>
	.people {
		max-inline-size: 18rem;
	}

	.person {
		display: grid;
	}
</style>
Options hold any content. An aria-disabled option is skipped by the keys and ignores clicks.

Horizontal

Horizontal
  • XS
  • S
  • M
  • L
  • XL
Code
<script lang="ts">
	import '@svelte-lean/styles/listbox.css';
	import type { ListboxChangeDetail } from '@svelte-lean/primitives/listbox';
	import { on } from 'svelte/events';

	const sizes = ['XS', 'S', 'M', 'L', 'XL'];
	let size = $state('M');

	function onSize(event: Event) {
		size = String((event as CustomEvent<ListboxChangeDetail>).detail.value);
	}
</script>

<!-- A row: ArrowRight and ArrowLeft (swapped under RTL), no wrap at the ends. -->
<ul
	role="listbox"
	aria-label="Size"
	aria-orientation="horizontal"
	data-slean="listbox"
	data-slean-orientation="horizontal"
	data-slean-loop="false"
	class="sizes"
	{@attach (node) => on(node, 'slean:change', onSize)}
>
	{#each sizes as option (option)}
		<li
			role="option"
			aria-selected={option === size}
			tabindex={option === size ? 0 : -1}
			data-slean-value={option}
		>
			{option}
		</li>
	{/each}
</ul>

<style>
	.sizes {
		inline-size: fit-content;
	}
</style>

Groups

Groups
Europe
Berlin
Istanbul
Lisbon
London
Paris
Americas
Chicago
Mexico City
New York
São Paulo
Asia
Dubai
Seoul
Singapore
Tokyo
Code
<script lang="ts">
	import '@svelte-lean/styles/listbox.css';

	const regions = [
		{ id: 'europe', name: 'Europe', zones: ['Berlin', 'Istanbul', 'Lisbon', 'London', 'Paris'] },
		{ id: 'americas', name: 'Americas', zones: ['Chicago', 'Mexico City', 'New York', 'São Paulo'] },
		{ id: 'asia', name: 'Asia', zones: ['Dubai', 'Seoul', 'Singapore', 'Tokyo'] }
	];
</script>

<!-- Manual selection: the arrows move focus, Space or Enter selects. The root wraps a list
     that scrolls. -->
<div data-slean="listbox" data-slean-selection="manual" class="zones">
	<div role="listbox" aria-label="Time zone" data-slean-part="list">
		{#each regions as region (region.id)}
			<div role="group" aria-labelledby="region-{region.id}">
				<div id="region-{region.id}" data-slean-part="group-label">{region.name}</div>
				{#each region.zones as zone (zone)}
					<div
						role="option"
						aria-selected={zone === 'Istanbul'}
						tabindex={zone === 'Istanbul' ? 0 : -1}
						data-slean-value={zone}
					>
						{zone}
					</div>
				{/each}
			</div>
		{/each}
	</div>
</div>

<style>
	.zones {
		max-inline-size: 16rem;
	}

	.zones [role='listbox'] {
		max-block-size: 14rem;
	}
</style>
Group labels come from role="group" and aria-labelledby; typing a letter jumps to the next match.

Form value

Plan
  • Free
  • Team
  • Business
Code
<script lang="ts">
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/listbox.css';

	const plans = ['Free', 'Team', 'Business'];
	let sent = $state('');

	function submit(event: SubmitEvent) {
		event.preventDefault();
		sent = String(new FormData(event.currentTarget as HTMLFormElement).get('plan'));
	}
</script>

<!-- The native part carries the value into the form; Reset puts it back and the list follows. -->
<form class="plans" onsubmit={submit} onreset={() => (sent = '')}>
	<div data-slean="listbox">
		<input hidden name="plan" value="Team" data-slean-part="native" />
		<ul role="listbox" aria-label="Plan" data-slean-part="list">
			{#each plans as plan (plan)}
				<li
					role="option"
					aria-selected={plan === 'Team'}
					tabindex={plan === 'Team' ? 0 : -1}
					data-slean-value={plan}
				>
					{plan}
				</li>
			{/each}
		</ul>
	</div>
	<div class="actions">
		<button type="submit" data-slean="button">Submit</button>
		<button type="reset" data-slean="button" data-variant="outlined" data-color="neutral">
			Reset
		</button>
	</div>
	{#if sent}<p role="status">Submitted: plan={sent}</p>{/if}
</form>

<style>
	.plans {
		display: grid;
		justify-items: start;
		gap: var(--slean-space-2);
		max-inline-size: 16rem;
	}

	.plans [data-slean='listbox'] {
		inline-size: 100%;
	}

	.actions {
		display: flex;
		gap: var(--slean-space-2);
	}
</style>
A hidden input part carries the value: select a plan and submit, then Reset.

Colors

Level
  • Low
  • Medium
  • High
  • Low
  • Medium
  • High
  • Low
  • Medium
  • High
Code
<script lang="ts">
	import '@svelte-lean/styles/listbox.css';

	const colors = ['success', 'warning', 'error'];
	const levels = ['Low', 'Medium', 'High'];
</script>

<!-- data-color picks the selected fill and the check mark. -->
<div class="colors">
	{#each colors as color (color)}
		<ul role="listbox" aria-label="Level ({color})" data-slean="listbox" data-color={color}>
			{#each levels as level (level)}
				<li
					role="option"
					aria-selected={level === 'Medium'}
					tabindex={level === 'Medium' ? 0 : -1}
					data-slean-value={level}
				>
					{level}
				</li>
			{/each}
		</ul>
	{/each}
</div>

<style>
	.colors {
		display: flex;
		flex-wrap: wrap;
		gap: var(--slean-space-3);
	}
</style>

Usage

Install @svelte-lean/primitives and @svelte-lean/styles. With @svelte-lean/vite the behavior registers itself for every data-slean="listbox"; without it, import the register module once.

npm install @svelte-lean/primitives
+layout.svelte or any client module
import '@svelte-lean/primitives/listbox/register';
stylesheets
import '@svelte-lean/styles/listbox.css';

Render the initial state completely: aria-selected on every option and exactly one tabindex="0". Listen to slean:change on the root to follow the selection; it fires before aria-selected is written and can be cancelled.

The options are one attribute each on the root: data-slean-multiple, data-slean-selection="manual", data-slean-orientation="horizontal" and data-slean-loop="false". For a form value and bind:value, put an <input hidden name data-slean-part="native"> beside the list in a wrapper root: the behavior writes it (comma-separated when multiple) and follows setValue() and a form reset.

options
<!-- Arrow keys move focus only; Space, Enter or a click select: -->
<ul role="listbox" aria-label="Fruit" data-slean="listbox" data-slean-selection="manual">

<!-- A row of options, ArrowRight and ArrowLeft (swapped under dir="rtl"), no wrap at the ends: -->
<ul
	role="listbox"
	aria-label="Size"
	aria-orientation="horizontal"
	data-slean="listbox"
	data-slean-orientation="horizontal"
	data-slean-loop="false"
>

Anatomy

PartElementdata-slean-partRequiredNotes
root<ul role="listbox" aria-label="…" data-slean="listbox"> or a wrapper element–yesThe listbox element itself, or an element around the list part. Options: data-slean-multiple, data-slean-selection, data-slean-orientation, data-slean-loop.
list<ul role="listbox" aria-label="…">listnoOnly when the root is a wrapper; exactly one. Set aria-multiselectable="true" with the multiple option and aria-orientation="horizontal" with the orientation option.
option<li role="option" aria-selected="…" tabindex="0 or -1" data-slean-value="…">–yesFound by role, no part attribute. Exactly one option has tabindex="0"; disabled options carry aria-disabled="true".
group<li role="group" aria-label="…">–noA section of options.
group-label<span>group-labelstyles onlyA group heading.
native<input hidden name="…">nativenoIn a wrapper root, outside the listbox: carries the value into forms and bind:value (comma-separated when multiple); setValue() and a form reset are followed.

Keyboard

KeyWhenResult
Tab/Shift+TabanywhereEnters the list on the tabindex="0" option (native)
ArrowDown/ArrowUpfocus on an option, verticalNext or previous enabled option, wrapping unless data-slean-loop="false"; selects it in automatic single-select mode, moves focus only otherwise
ArrowRight/ArrowLeftfocus on an option, horizontalAs above; swapped under dir="rtl"
Home/Endfocus on an optionFirst or last enabled option; selects it in automatic single-select mode
a characterfocus on an optionTypeahead over option text; a repeated character cycles; selects in automatic single-select mode
Space/Enterfocus on an optionSelects it (single-select, the way to select in manual mode) or toggles it (multi-select)
Shift+ArrowDown/Shift+ArrowUpfocus on an option, multi-selectMoves and adds the focused option and the target to the selection
Ctrl+A/Cmd+Afocus on an option, multi-selectSelects every enabled option

Styling

listbox.css styles the list and its rows, the selected, hover and disabled states (the selected fill and the check mark follow data-color), a group label, the horizontal row and the multi-select check mark. Options are focused directly, so the file draws its own inset focus ring for :focus-visible. The tokens it reads:

TokenDefault (light)Applies to
--slean-space-1calc(var(--slean-spacing) * 1)padding, gap, padding-block
--slean-bordervar(--slean-neutral-6)border
--slean-radius-mdvar(--slean-radius)border-radius
--slean-surfaceoklch(100% 0 0)background
--slean-fgvar(--slean-neutral-12)color
--slean-space-2calc(var(--slean-spacing) * 2)gap, padding-inline, padding-inline-start, inset-inline-start
--slean-control-height-sm2remmin-block-size
--slean-radius-smcalc(var(--slean-radius) * 0.6)border-radius
--slean-text-sm0.875remfont-size
--slean-mutedvar(--slean-neutral-3)background
--slean-option-activevar(--slean-muted)background
--slean-focus-ringvar(--slean-focus-ring-width) solid var(--slean-focus-ring-color)outline
--slean-focus-ring-width2pxoutline-offset
--slean-color-softvar(--slean-primary-soft)background
--slean-color-soft-textvar(--slean-primary-soft-text)color, box-shadow
--slean-color-mainvar(--slean-primary-main)background
--slean-icon-checkurl("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M3.5 8.5l3 3 6-7' stroke='black' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round' fill='none'/%3E%3C/svg%3E")mask
--slean-fg-mutedvar(--slean-neutral-11)color
--slean-text-xs0.75remfont-size
--slean-font-weight-medium500font-weight

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

Variant attributes: data-slean-orientation (horizontal); data-slean-multiple.

Controlled integration

slean:change carries value and previous: in a single-select root the selected data-slean-value and the one before (or null), in a multi-select root arrays in document order. selectOptions() writes a selection from script; listboxOptions() and listboxValue() read the DOM.

toppings.svelte
<script lang="ts">
	import {
		listboxOptions,
		listboxValue,
		selectOptions
	} from '@svelte-lean/primitives/listbox';

	let root: HTMLElement;
	let selected = $state<string[]>(['cheese']);

	function clear() {
		// Pass every option that should stay selected; returns false when a listener cancelled.
		selectOptions(root, []);
		selected = listboxValue(root);
	}

	function selectAll() {
		selectOptions(root, listboxOptions(root));
		selected = listboxValue(root);
	}
</script>

<div id="toppings" data-slean="listbox" data-slean-multiple bind:this={root}>
	…
</div>
<button type="button" onclick={clear}>Clear</button>
<button type="button" onclick={selectAll}>Select all</button>

Under the hood

Runtime and size
Tier
1 · Delegated micro-behavior
Behavior JS
2357 B brotli · 2612 B gzip · packages/primitives/artifacts/size.json · method
Platform features
role="listbox", role="option", aria-selected, roving tabindex, :dir(rtl)
Shared listeners
click, keydown, change, reset
Per-instance listeners
none
Lazy state
none
Native base
ARIA listbox markup (role=listbox, option)

Four listeners (click, keydown, change and reset, the last two for the optional native part) serve every listbox on the page, and one typeahead buffer is created on first use. There is no per-root state, no WeakMap, no observer and no layout read; the unit test asserts that the behavior source contains none of them. The listbox-only fixture measures what a consumer build ships.

Why this implementation

For one choice inside a form the native <select> fits better: the browser owns the popup, the keyboard and form participation. A listbox is for what a select does not do: a list visible the whole time, several selected options with Shift and Ctrl keys, options with more than a text label.

ARIA gives the roles and states and the browser gives focus and the tab order; what is missing is the movement between options, the roving tab stop, typeahead and the selection rules of the APG pattern. Svelte Lean adds only that, as one behavior shared by every listbox on the page. The selection is never mirrored: every event reads aria-selected from the DOM and writes it back, so a listbox the application re-renders cannot disagree with the behavior.

The browser owns

  • the tab order: Tab enters the list on the option with tabindex="0"
  • the listbox and option roles, aria-selected and aria-multiselectable announcements
  • the click and keydown events routed to the behavior
  • scrolling the focused option into view

Svelte Lean owns

  • selection on click, Space and Enter; arrow keys, Home and End; typeahead; automatic and manual modes
  • multi-select toggling, Shift+Arrow extension and Ctrl+A
  • writing aria-selected and the roving tabindex
  • the cancelable slean:change event and selectOptions(), listboxOptions(), listboxValue()
  • the optional native part: writing the form value, following setValue() and a form reset
  • development validation of the markup
  • listbox.css and the contract
Accessibility
  • Root: the role="listbox" element with a name, or a wrapper around a data-slean-part="list" with that role. aria-multiselectable="true" goes with data-slean-multiple and aria-orientation="horizontal" with data-slean-orientation="horizontal"; development validation checks that they agree.
  • Options are role="option" elements with data-slean-value, aria-selected and a tabindex; any element works. Ids are authored; the behavior generates none.
  • A roving tab stop: after every move or click exactly one option has tabindex="0", and a click focuses the option. In manual single-select and in multi-select mode, focus moves without changing the selection until Space, Enter or a click.
  • aria-disabled="true" on the root skips routing. A disabled option is skipped by arrows, Home, End, typeahead and Ctrl+A, and its clicks, Space and Enter are ignored.
  • Direction is read from the nearest dir attribute (dir="auto" through :dir(rtl)); under RTL with horizontal orientation, ArrowRight moves to the previous option.
  • When a slean:change listener cancels, the selection stays; focus and the tab stop still move.
Platform features
FeatureBaselineOutside the target
ARIA listbox roles and states (listbox, option, group, aria-selected, aria-multiselectable, aria-orientation, aria-disabled)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 markup stays: the selected options are marked and readable, and nothing can be changed. A native part submits the server-rendered value; a form whose value must change without script uses a native <select> or checkboxes.

Server rendering and hydration

The server renders the selection and the tab stop, and no ids are generated. The register module is safe to import on the server (packages/primitives/tests/ssr.test.ts); the playground’s SSR page renders a listbox and asserts that hydration changes nothing.

Nothing runs at hydration: the shared listeners were installed when the behavior registered. Before the register module has loaded, a click on an option changes nothing, as the playground’s delayed-hydration test asserts; after it, the same click selects.

Compatibility

ARIA 1.2 roles, ES2022 output and composedPath(); :dir(rtl) only resolves dir="auto", with a guard where the pseudo-class is missing. No virtualization, drag selection, or Shift+click and Ctrl+click ranges. Tested in Chromium; Firefox and WebKit runs do not exist yet.

Tests and source