Autocomplete

Example

<label for="autocomplete-team">Team</label>
<input
	id="autocomplete-team"
	name="team"
	list="autocomplete-team-options"
	autocomplete="off"
	data-slean="autocomplete"
/>
<datalist id="autocomplete-team-options">
	<option value="Engineering"></option>
	<option value="Design"></option>
	<option value="Operations"></option>
	<option value="Growth"></option>
</datalist>

<script lang="ts">
	// Nothing to import: the browser owns the field and the list. The stylesheet is optional.
	import '@svelte-lean/styles/autocomplete.css';

	let team = $state('');
</script>

<label for="autocomplete-team">Team</label>
<input
	id="autocomplete-team"
	name="team"
	list="autocomplete-team-options"
	autocomplete="off"
	bind:value={team}
	data-slean="autocomplete"
/>
<datalist id="autocomplete-team-options">
	<option value="Engineering"></option>
	<option value="Design"></option>
	<option value="Operations"></option>
	<option value="Growth"></option>
</datalist>

Why this implementation exists

Suggestions under a text field are a combobox, and a combobox built in script needs a popup, filtering, an active option and the ARIA that ties them together. When the options are plain text and free text is allowed, <datalist> gives the same result with the browser doing all of it.

The trade is control: the browser draws the list, matches by its own rule and takes no CSS for it. For options with their own markup, or a value restricted to the list, use the Combobox.

Usage

The markup needs no package. Install @svelte-lean/styles for the stylesheet; @svelte-lean/primitives adds the typed contract and nothing at runtime.

npm install @svelte-lean/styles

pnpm add @svelte-lean/styles

yarn add @svelte-lean/styles

bun add @svelte-lean/styles

import '@svelte-lean/styles/autocomplete.css';

Point the input’s list at the datalist’s id. Each <option value> is a suggestion; the value is what the field receives.

autocomplete="off" asks the browser not to mix its history of past entries into the list.

Change the suggestions by rendering new <option> elements, for example from an {#each} over fetched results; the browser filters whatever is there.

Anatomy

Runtime profile

Tier 0: the field has no behavior module, and the Vite plugin maps autocomplete to no module. Matching, the list and its keyboard are the browser’s.

Accessibility contract

• HTML-AAM maps a text input with a list attribute to the combobox role; no ARIA is added.
• A label through <label for>; a hint through aria-describedby.
• The list’s keyboard (ArrowDown, ArrowUp, Enter, Escape) is the browser’s and differs slightly between browsers.

Keyboard

Platform features

Without JavaScript

Fully functional: typing, choosing a suggestion and submitting need no script.

Server rendering

Static HTML: the input and the datalist, with its options, render on the server.

Before hydration

Nothing is attached; the field and its list work before and after hydration alike.

Styling

autocomplete.css draws the text box from the tokens and dims the list indicator some browsers draw inside the field. The list is rendered outside the page and takes no CSS. The tokens it reads:

State selectors the stylesheet targets, all from the platform or ARIA: ::-webkit-calendar-picker-indicator, ::placeholder, :disabled, :focus-visible, :hover, :user-invalid, [aria-invalid="true"].

Variant attributes: data-status (warning, error).

Controlled integration

The options are markup, so the application changes them by rendering. Bind the value to read what was typed or chosen.

<script lang="ts">
	let { cities }: { cities: string[] } = $props();
	let city = $state('');
</script>

<input id="autocomplete-city" name="city" list="autocomplete-city-options" bind:value={city}
	data-slean="autocomplete" />
<!-- New options are new <option> elements; the browser filters them as the user types. -->
<datalist id="autocomplete-city-options">
	{#each cities as name (name)}
		<option value={name}></option>
	{/each}
</datalist>

Compatibility notes

<input list> is Baseline 2019. <datalist> is not Baseline: how options are matched, whether an option’s label is shown and whether a list appears at all differ between browsers. Where no list appears, the field is a plain text input and the typed value is still submitted.

Testing

• apps/playground/tests/primitives/inputs-overlays.spec.ts Playwright, with page JavaScript enabled and disabled, and axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)

Source

• packages/primitives/src/autocomplete/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/autocomplete/contract.ts typed constants: name, tier, base, parts, options, events
• packages/styles/css/autocomplete.css the optional stylesheet