Primitives Forms
Listbox
A visible list to pick one or several options from, where a native select falls short: an always-open list, multi-select, rich options.
Markdown version of this page, for assistants (Markdown for AI)
On this page
- 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>Examples
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>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>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>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
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>Form value
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>Colors
- 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/primitivespnpm add @svelte-lean/primitivesyarn add @svelte-lean/primitivesbun add @svelte-lean/primitivesimport '@svelte-lean/primitives/listbox/register';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.
<!-- 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
| Part | Element | data-slean-part | Required | Notes |
|---|---|---|---|---|
| root | <ul role="listbox" aria-label="…" data-slean="listbox"> or a wrapper element | – | yes | The 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="…"> | list | no | Only 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="…"> | – | yes | Found by role, no part attribute. Exactly one option has tabindex="0"; disabled options carry aria-disabled="true". |
| group | <li role="group" aria-label="…"> | – | no | A section of options. |
| group-label | <span> | group-label | styles only | A group heading. |
| native | <input hidden name="…"> | native | no | In 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
| Key | When | Result |
|---|---|---|
| Tab/Shift+Tab | anywhere | Enters the list on the tabindex="0" option (native) |
| ArrowDown/ArrowUp | focus on an option, vertical | Next or previous enabled option, wrapping unless data-slean-loop="false"; selects it in automatic single-select mode, moves focus only otherwise |
| ArrowRight/ArrowLeft | focus on an option, horizontal | As above; swapped under dir="rtl" |
| Home/End | focus on an option | First or last enabled option; selects it in automatic single-select mode |
| a character | focus on an option | Typeahead over option text; a repeated character cycles; selects in automatic single-select mode |
| Space/Enter | focus on an option | Selects it (single-select, the way to select in manual mode) or toggles it (multi-select) |
| Shift+ArrowDown/Shift+ArrowUp | focus on an option, multi-select | Moves and adds the focused option and the target to the selection |
| Ctrl+A/Cmd+A | focus on an option, multi-select | Selects 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:
| Token | Default (light) | Applies to |
|---|---|---|
--slean-space-1 | calc(var(--slean-spacing) * 1) | padding, gap, padding-block |
--slean-border | var(--slean-neutral-6) | border |
--slean-radius-md | var(--slean-radius) | border-radius |
--slean-surface | oklch(100% 0 0) | background |
--slean-fg | var(--slean-neutral-12) | color |
--slean-space-2 | calc(var(--slean-spacing) * 2) | gap, padding-inline, padding-inline-start, inset-inline-start |
--slean-control-height-sm | 2rem | min-block-size |
--slean-radius-sm | calc(var(--slean-radius) * 0.6) | border-radius |
--slean-text-sm | 0.875rem | font-size |
--slean-muted | var(--slean-neutral-3) | background |
--slean-option-active | var(--slean-muted) | background |
--slean-focus-ring | var(--slean-focus-ring-width) solid var(--slean-focus-ring-color) | outline |
--slean-focus-ring-width | 2px | outline-offset |
--slean-color-soft | var(--slean-primary-soft) | background |
--slean-color-soft-text | var(--slean-primary-soft-text) | color, box-shadow |
--slean-color-main | var(--slean-primary-main) | background |
--slean-icon-check | url("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-muted | var(--slean-neutral-11) | color |
--slean-text-xs | 0.75rem | font-size |
--slean-font-weight-medium | 500 | font-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.
<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/· methodprimitives/ artifacts/ size.json - 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 adata-slean-part="list"with that role.aria-multiselectable="true"goes withdata-slean-multipleandaria-orientation="horizontal"withdata-slean-orientation="horizontal"; development validation checks that they agree. - Options are
role="option"elements withdata-slean-value,aria-selectedand atabindex; 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
dirattribute (dir="auto"through:dir(rtl)); under RTL with horizontal orientation, ArrowRight moves to the previous option. - When a
slean:changelistener cancels, the selection stays; focus and the tab stop still move.
Platform features
| Feature | Baseline | Outside 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 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 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
packages/primitives/tests/listbox.test.tsunit tests (happy-dom): click, arrows, Home/End, typeahead, selection modes, multi-select, disabled, RTL, nesting, cancellation, 1000 rootsapps/playground/tests/primitives/listbox.spec.tsPlaywright: real focus movement, :focus-visible, typeahead timing, multi-select keys, RTL, slean:change, 1000 rootsapps/playground/tests/primitives/nested.spec.tsa listbox inside a tab panelfixtures/listbox-onlyconsumer build: only the listbox registration ships; tabs, menu, select and autocomplete are absentapps/playground/tests/primitives/a11y.spec.tsaxe on every playground page and on open dialog, popover and menu states
packages/primitives/src/listbox/contract.mdthe contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behaviorpackages/primitives/src/listbox/contract.tstyped constants: name, tier, base, parts, options, eventspackages/primitives/src/listbox/behavior.tsthe behavior definition, selectOptions(), listboxOptions(), listboxValue()packages/primitives/src/listbox/register.tsthe registration module, the only side effectpackages/primitives/src/listbox/validate.tsdevelopment validation messagespackages/styles/css/listbox.cssthe optional stylesheet