Combobox

Example

<label for="city-input">City</label>
<div id="city" data-slean="combobox">
	<input
		id="city-input"
		type="text"
		role="combobox"
		aria-expanded="false"
		aria-controls="city-list"
		aria-autocomplete="list"
		autocomplete="off"
		placeholder="Select a city"
		data-slean-part="input"
	/>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<button
		type="button"
		tabindex="-1"
		aria-label="Show cities"
		aria-expanded="false"
		data-slean-part="toggle"
	></button>
	<div id="city-popup" popover="manual" data-slean-part="popup">
		<ul id="city-list" role="listbox" aria-label="Cities">
			<li id="city-ankara" role="option" aria-selected="false" data-slean-value="ankara">Ankara</li>
			<li id="city-berlin" role="option" aria-selected="false" data-slean-value="berlin">Berlin</li>
			<li
				id="city-cairo"
				role="option"
				aria-selected="false"
				aria-disabled="true"
				data-slean-value="cairo"
			>
				Cairo
			</li>
			<li id="city-lisbon" role="option" aria-selected="false" data-slean-value="lisbon">Lisbon</li>
			<li id="city-oslo" role="option" aria-selected="false" data-slean-value="oslo">Oslo</li>
		</ul>
		<p data-slean-part="empty" hidden>No city matches</p>
	</div>
</div>

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

<label for="city-input">City</label>
<div id="city" data-slean="combobox">
	<input
		id="city-input"
		type="text"
		role="combobox"
		aria-expanded="false"
		aria-controls="city-list"
		aria-autocomplete="list"
		autocomplete="off"
		placeholder="Select a city"
		data-slean-part="input"
	/>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<button
		type="button"
		tabindex="-1"
		aria-label="Show cities"
		aria-expanded="false"
		data-slean-part="toggle"
	></button>
	<div id="city-popup" popover="manual" data-slean-part="popup">
		<ul id="city-list" role="listbox" aria-label="Cities">
			<li id="city-ankara" role="option" aria-selected="false" data-slean-value="ankara">Ankara</li>
			<li id="city-berlin" role="option" aria-selected="false" data-slean-value="berlin">Berlin</li>
			<li
				id="city-cairo"
				role="option"
				aria-selected="false"
				aria-disabled="true"
				data-slean-value="cairo"
			>
				Cairo
			</li>
			<li id="city-lisbon" role="option" aria-selected="false" data-slean-value="lisbon">Lisbon</li>
			<li id="city-oslo" role="option" aria-selected="false" data-slean-value="oslo">Oslo</li>
		</ul>
		<p data-slean-part="empty" hidden>No city matches</p>
	</div>
</div>

Last slean:select on the example: No selection yet.. Bound value: empty.

Why this implementation exists

A combobox is a text field first. Typing, the caret, selection, Backspace, Delete, Home, End, the browser's shortcuts and IME composition are the platform's, and a library that intercepts them breaks input in languages that compose. The popup is a popover: the browser owns the top layer and showPopover(), the stylesheet owns placement through CSS anchor positioning. What ARIA asks for on top is the part Svelte Lean adds: aria-expanded, aria-activedescendant moved by ArrowDown and ArrowUp while focus never leaves the input, acceptance on Enter and click, Escape, and a filter for a static list. Since ADR 0007 the field is the shared control shell of the select and the date picker: the whole field is the click target, a click opens the list, the chosen option is checked and a clear button sits inside the field. Unlike tabs and menu, an open popup needs to know about a press anywhere on the page, which is a listener with a lifetime: it exists while one popup is open and not otherwise. That is why the combobox is Tier 2, and why it is the proof for shipping invariant D of ADR 0005: a page with a hundred combobox roots allocates nothing until one is used.

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="combobox" gets import '@svelte-lean/primitives/combobox/register' appended to its compiled module; without the plugin, write that import yourself once. The field, the clear button and the chevron, the popup surface, its placement under the root and the option rows come from control.css, the control shell shared with the select and the date picker; load it before combobox.css. The clear button reads :placeholder-shown, so give the input a placeholder (placeholder=" " when there is none).

// 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/combobox/register';

import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
// The field, the icons, the popup and the option rows are the shared control shell.
import '@svelte-lean/styles/control.css';
import '@svelte-lean/styles/combobox.css';

Give the root an id: an option without one gets a deterministic id from it the first time it becomes active, which is what aria-activedescendant needs. Use popover="manual" for the popup, so that nothing can steal focus from the input; the behavior owns dismissal. The options are one attribute each on the root:

<!-- Match the start of the label; the first match becomes active while typing and Tab accepts it: -->
<div id="city" data-slean="combobox" data-slean-filter="startsWith" data-slean-autoselect>

<!-- ArrowDown and ArrowUp stop at the ends instead of wrapping: -->
<div id="city" data-slean="combobox" data-slean-loop="false">

<!-- A popup toggled with the hidden attribute instead of a popover (browsers without the Popover API): -->
<div id="city-popup" hidden data-slean-part="popup">

Anatomy

Runtime profile

The bytes in the runtime block are the production build of @svelte-lean/primitives/combobox/register including the shared kernel, from packages/primitives/artifacts/size.json (2564 B brotli · 2849 B gzip), against 1932 B brotli for the menu. A consumer sees the same bytes: the combobox-only fixture builds to one Svelte Lean chunk of 2564 B brotli, and that chunk contains no tabs, menu or listbox module.

Seven shared listeners serve every combobox on the page: click, keydown, input, pointerdown, pointerover, focusout and toggle. Per root, the first time its popup opens (a click in the field, an arrow key, an input event that leaves a match, a popup shown by script) creates one small object in a WeakMap holding the session; while the popup is open the session holds one AbortController and one document pointerdown listener, which closes the popup on a press outside the root. Closing aborts the session; focus leaving the root deletes the entry. A root nobody has touched has no entry, and the number of entries on a page follows the roots that were used, not the roots that exist. The playground asserts this with a hundred roots in a real browser and with a thousand in the unit test; the proof page shows the live controller count in a development build.

Accessibility contract

• Input: <input type="text"> with role="combobox", aria-expanded (written by the behavior), aria-controls naming the listbox, aria-autocomplete="list" (or "none" with data-slean-filter="none"), autocomplete="off" and an accessible name. aria-activedescendant is written by the behavior.
• Popup: a popover="manual" element or one toggled with hidden, containing one role="listbox" with a name and role="option" children with ids. The active option carries aria-selected="true" and data-slean-active; options the filter hides carry hidden.
• Focus: DOM focus stays in the input at all times; the active option is announced through aria-activedescendant. Opening and closing never move focus away from the input; accepting keeps it there. A press anywhere in the root but the input (an option, the toggle, the clear button, the padding of the field) is prevented from moving focus, so the click still arrives and no focusout closes the popup.
• Toggle and clear: <button type="button" tabindex="-1"> with a name; the input is the tab stop. The toggle's aria-expanded follows the input's. The option that holds the input's value carries data-slean-selected (the check mark); it is styling, the selection announced to assistive technology is the input's value.
• Disabled: data-slean-disabled or aria-disabled="true" on the root skips routing; with the native disabled on the input the platform delivers no key or input event to it and the behavior ignores clicks on the toggle and the options; an option with aria-disabled="true" is skipped by the arrows and by autoselect and ignores clicks.
• IME: keys during a composition (isComposing, or keyCode 229 where the state is reported late) are ignored entirely, so Enter that commits a candidate never accepts an option. Home, End, Shift and Ctrl with an arrow are never intercepted.
• Development validation warns about a missing or wrong input, popup, listbox reference, autocomplete, name, toggle attributes, options without ids when the root has none, and popover="auto".

Keyboard

Keys whose target is not the input part (the toggle, content inside the popup) are ignored. Alt+ArrowUp is not handled. Vertical only: ArrowLeft and ArrowRight move the caret, and there is nothing to flip under RTL.

Platform features

Without JavaScript

The input is a plain text field: the user types a value and the form submits it. @media (scripting: none) in combobox.css hides the toggle and the clear button, which could do nothing; the popup stays closed and the options are not reachable. Authors who need the list without script render it inline (no popover, no hidden) or use a native <datalist>. The playground's delayed-hydration test types into the input before any script has arrived and reads the value back.

Server rendering

Static HTML: the input renders with its value, aria-expanded="false" and no aria-activedescendant; the popup is closed; every option is visible. No ids are generated on the server and none at hydration. The register module is safe to import on the server (packages/primitives/tests/ssr.test.ts); the playground's SSR page renders a combobox and asserts the server HTML.

Before hydration

Typing works before any script because the input is native. The popup, the arrows and the filter need the register module, which evaluates before the component code once the scripts arrive. Hydration attaches nothing to a root: the seven listeners are on the document, and the controller for a root exists only after its first interaction.

Styling

control.css draws the field: the border, hover, the focus halo, sizes (data-size), status (data-status) and a disabled input; the clear button and the chevron as icon masks from the --slean-icon-* tokens; the popup surface with its open transition; the option rows, the active option, the check mark of the chosen option, the disabled options and the empty message. The popup, popover or hidden-toggled, is placed under the root with CSS anchor positioning: the root carries an anchor name scoped to its own subtree, so many fields on a page do not interfere, and it stays unpositioned, because the anchor rules exclude the containing block of the positioned element. Without anchor positioning a hidden-toggled popup is positioned under the root with absolute positioning and a popover popup keeps the platform's centered placement. combobox.css only hides the buttons without scripting. The tokens of both files and the states they target:

State selectors the stylesheet targets, all from the platform or ARIA: ::placeholder, :disabled, :empty, :focus-visible, :focus-within, :hover, :placeholder-shown, :popover-open, :user-invalid, [aria-disabled="true"], [aria-expanded="true"], [aria-invalid="true"], [hidden], [popover], [role="listbox"], [role="option"].

Variant attributes: data-status (error, warning); data-size (sm, lg); data-slean-active; data-slean-selected.

Controlled integration

What exists today: the root dispatches a bubbling, cancelable slean:select CustomEvent before the input is written, with detail of type ComboboxSelectDetail (value, label, option); preventDefault() keeps the input and the popup as they are. After writing, the behavior dispatches a bubbling input event on the field, so bind:value sees the accepted label; Escape clearing the input does the same. openCombobox(), closeCombobox(), acceptOption(), filterOptions(), activeOption() and isComboboxOpen() from @svelte-lean/primitives/combobox are the helpers. There are no slean:open or slean:close events: a popover popup dispatches the native toggle event, and aria-expanded can be observed.

<script lang="ts">
	import { closeCombobox, type ComboboxSelectDetail } from '@svelte-lean/primitives/combobox';

	let root: HTMLElement;
	// The behavior dispatches a bubbling input event after it writes the field (an accepted
	// option, Escape clearing), so bind:value follows the accepted label.
	let city = $state('');
	let selected = $state<string | null>(null);

	$effect(() => {
		// slean:select bubbles from the root before the input is written; detail has the option's
		// value, its label and the element. preventDefault() keeps the input and the popup as they are.
		const onSelect = (event: Event) => {
			const { value } = (event as CustomEvent<ComboboxSelectDetail>).detail;
			selected = value;
		};
		root.addEventListener('slean:select', onSelect);
		return () => root.removeEventListener('slean:select', onSelect);
	});
</script>

<label for="city-input">City</label>
<div id="city" data-slean="combobox" bind:this={root}>
	<input id="city-input" … data-slean-part="input" bind:value={city} />
	…
</div>
<p>Typed: {city}; accepted: {selected ?? 'none'}</p>
<button type="button" onclick={() => closeCombobox(root)}>Close the popup from outside</button>

For remote or computed lists, data-slean-filter="none" leaves the options to the application: it listens to input, renders what it wants, and the behavior navigates and accepts what is in the DOM when a key arrives. Options are read on every event and never cached, so a list that changes between two keys cannot leave the controller pointing at a stale index.

<script lang="ts">
	// data-slean-filter="none": the application renders the options; the behavior navigates and
	// accepts whatever is in the DOM when a key arrives. Debouncing, requests and the empty
	// state are the application's.
	let results = $state<{ id: string; name: string }[]>([]);
	let pending = $state(false);
	let timer: ReturnType<typeof setTimeout>;

	function search(event: Event) {
		const query = (event.currentTarget as HTMLInputElement).value;
		clearTimeout(timer);
		pending = true;
		timer = setTimeout(async () => {
			results = await fetchCities(query);
			pending = false;
		}, 250);
	}
</script>

<label for="city-input">City</label>
<div id="city" data-slean="combobox" data-slean-filter="none">
	<input
		id="city-input"
		type="text"
		role="combobox"
		aria-expanded="false"
		aria-controls="city-list"
		aria-autocomplete="list"
		autocomplete="off"
		placeholder="Search cities"
		data-slean-part="input"
		oninput={search}
	/>
	<div id="city-popup" popover="manual" data-slean-part="popup">
		<ul id="city-list" role="listbox" aria-label="Cities" aria-busy={pending}>
			{#each results as city (city.id)}
				<li id="city-{city.id}" role="option" aria-selected="false" data-slean-value={city.id}>
					{city.name}
				</li>
			{/each}
		</ul>
		{#if results.length === 0 && !pending}
			<p data-slean-part="empty">No city matches.</p>
		{/if}
	</div>
</div>

Compatibility notes

The combobox depends on the Popover API (Baseline newly available since April 2024) for a popover popup, with a hidden-toggled popup as the documented path for browsers without it, and on CSS anchor positioning (Chrome 125, Safari 26; not Baseline) for placement, with the fallbacks above. showPopover({ source }) is passed as an option that browsers without it ignore. The behavior needs ES2022 output, composedPath(), AbortSignal on addEventListener and KeyboardEvent.isComposing. Tested in Chromium, including IME composition through the DevTools protocol; Firefox and WebKit runs do not exist yet, and whether a cancelled pointerdown keeps focus in the input there is not measured. The policy is on Browser support.

Examples

Command palette

A command palette is a composition, not a primitive: a native modal dialog holding a combobox whose popup is toggled with hidden, so the list stays inside the dialog instead of opening another top-layer element. The dialog owns the top layer, the backdrop, Escape and focus return; the combobox owns filtering and the active option; slean:select runs the command and closes the dialog.

<script lang="ts">
	// A composition: a native modal dialog holding a combobox with a hidden-toggled popup.
	import '@svelte-lean/styles/button.css';
	import '@svelte-lean/styles/dialog.css';
	import '@svelte-lean/styles/control.css';
	import '@svelte-lean/styles/combobox.css';
	import type { ComboboxSelectDetail } from '@svelte-lean/primitives/combobox';
	import { on } from 'svelte/events';

	let dialog: HTMLDialogElement;
	const commands = [
		['new', 'New file'],
		['open', 'Open recent'],
		['theme', 'Toggle theme'],
		['settings', 'Settings']
	];

	function run(event: Event) {
		const { value } = (event as CustomEvent<ComboboxSelectDetail>).detail;
		dialog.close(value); // the dialog returns focus to the button that opened it
	}
</script>

<button type="button" commandfor="palette" command="show-modal">Command palette</button>

<dialog id="palette" bind:this={dialog} data-slean="dialog" aria-label="Command palette">
	<div data-slean="combobox" data-slean-autoselect {@attach (node) => on(node, 'slean:select', run)}>
		<input type="text" role="combobox" aria-label="Command" aria-expanded="false"
			aria-controls="palette-list" aria-autocomplete="list" autocomplete="off"
			data-slean-part="input" />
		<div hidden data-slean-part="popup">
			<ul id="palette-list" role="listbox" aria-label="Commands">
				{#each commands as [value, label] (value)}
					<li id="palette-{value}" role="option" aria-selected="false" data-slean-value={value}>
						{label}
					</li>
				{/each}
			</ul>
		</div>
	</div>
</dialog>

Testing

• packages/primitives/tests/combobox.test.ts unit tests (happy-dom with a Popover API shim): lazy controller with 1000 roots, native editing never prevented, keyboard, filters, pointer, popup events, validation
• apps/playground/tests/primitives/combobox.spec.ts Playwright: native typing and caret, the real popover in the top layer, anchor placement, aria-activedescendant, filters, autoselect, an asynchronous list, a modal dialog, IME composition over the DevTools protocol
• apps/playground/tests/primitives/lazy.spec.ts 100 roots: no controller after load, one per interacted root, released on close and focus loss; the same shared listeners for 1 and 100 roots
• apps/playground/tests/primitives/nested.spec.ts a combobox inside a modal dialog
• apps/playground/tests/stress/memory.spec.ts 200 open/close cycles: heap, DOM nodes and listeners back at baseline
• fixtures/combobox-only consumer build: only the combobox registration and lazyState ship; tabs, menu and listbox are absent
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states

Source

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