Select

Example

<label id="fruit-label" for="fruit-native">Fruit</label>
<div id="fruit" data-slean="select">
	<select id="fruit-native" name="fruit" data-slean-part="native">
		<option value="" hidden>Select a fruit</option>
		<option value="apple">Apple</option>
		<option value="banana">Banana</option>
		<option value="cherry" disabled>Cherry</option>
		<option value="grape">Grape</option>
		<option value="mango">Mango</option>
	</select>
	<button
		type="button"
		role="combobox"
		aria-haspopup="listbox"
		aria-expanded="false"
		aria-controls="fruit-list"
		aria-labelledby="fruit-label"
		data-slean-part="trigger"
	>
		<span data-slean-part="value"></span>
		<span data-slean-part="placeholder">Select a fruit</span>
	</button>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="toggle" aria-hidden="true"></span>
	<div popover="manual" data-slean-part="popup">
		<ul id="fruit-list" role="listbox" aria-labelledby="fruit-label"></ul>
	</div>
</div>

<script lang="ts">
	// With @svelte-lean/vite the register import is injected for the static data-slean="select".
	import '@svelte-lean/styles/control.css';
	import '@svelte-lean/styles/select.css';

	const FRUITS = [
		{ value: 'apple', label: 'Apple' },
		{ value: 'banana', label: 'Banana' },
		{ value: 'cherry', label: 'Cherry', disabled: true },
		{ value: 'grape', label: 'Grape' },
		{ value: 'mango', label: 'Mango' }
	];

	// The native select holds the value; bind:value follows the change event the behavior
	// dispatches after it writes it.
	let fruit = $state('');
	const label = (value: string) => FRUITS.find((f) => f.value === value)?.label ?? '';
</script>

<label id="fruit-label" for="fruit-native">Fruit</label>
<div id="fruit" data-slean="select">
	<select id="fruit-native" name="fruit" data-slean-part="native" bind:value={fruit}>
		<option value="" hidden>Select a fruit</option>
		{#each FRUITS as f (f.value)}
			<option value={f.value} disabled={f.disabled}>{f.label}</option>
		{/each}
	</select>
	<button
		type="button"
		role="combobox"
		aria-haspopup="listbox"
		aria-expanded="false"
		aria-controls="fruit-list"
		aria-labelledby="fruit-label"
		data-slean-part="trigger"
	>
		<span data-slean-part="value">{label(fruit)}</span>
		<span data-slean-part="placeholder">Select a fruit</span>
	</button>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="toggle" aria-hidden="true"></span>
	<div popover="manual" data-slean-part="popup">
		<ul id="fruit-list" role="listbox" aria-labelledby="fruit-label"></ul>
	</div>
</div>

Why this implementation exists

The native <select> has the value, form submission, autofill, disabled options and optgroups, and it is the right control without JavaScript. Its interface is not the same everywhere: the customizable select (appearance: base-select) is in Chrome and Safari 27, not in Firefox, and the platform menus cannot show a placeholder, a clear button or tags. ADR 0007 keeps the native select as the value and draws the field over it.

The owned field is the control shell every form control shares (control.css). The popup listbox is empty in the markup: the behavior renders it from the native options each time it opens, so the options the application renders into the <select> are the only list there is, and the value is never mirrored. Focus stays on the trigger and the active option is announced through aria-activedescendant, the APG select-only combobox.

Usage

Install @svelte-lean/primitives for the behavior and @svelte-lean/styles for the stylesheet. With @svelte-lean/vite the registration is injected for every static data-slean="select"; without it, import the register module once.

npm install @svelte-lean/primitives

pnpm add @svelte-lean/primitives

yarn add @svelte-lean/primitives

bun add @svelte-lean/primitives

import '@svelte-lean/primitives/select/register';

import '@svelte-lean/styles/control.css';
import '@svelte-lean/styles/select.css';

Wrap a native <select data-slean-part="native"> in <div data-slean="select"> with a role="combobox" trigger (holding the value and placeholder parts), an optional clear button and chevron, and a popover="manual" popup with an empty role="listbox". A hidden first option is the placeholder.

Bind the native select with bind:value and render the chosen label in the value part; the behavior writes the native select, dispatches input and change, and updates the label through its text node. After setting the value in script, dispatch change on the native select.

For search inside the list use Combobox. A bare <select data-slean="select"> is the Tier 0 styled native select (see below).

Anatomy

Runtime profile

Tier 2: a lazy scoped controller. Seven shared listeners (click, keydown, pointerdown, pointerover, focusout, change and toggle in the capture phase) serve every select on the page. A root gets a WeakMap entry on its first interaction and, while its popup is open, one document pointerdown listener that closes it on a press outside; focus leaving the root deletes the entry. The Vite plugin injects the register module for a select marker on a <div> and nothing for the same marker on a bare <select>.

Accessibility contract

• The trigger is a role="combobox" with aria-haspopup="listbox", aria-expanded (written), aria-controls naming the listbox and aria-labelledby naming the label; it keeps DOM focus and aria-activedescendant names the active option.
• Options are role="option" with aria-selected on the chosen ones and aria-disabled for a disabled native option; an optgroup is a role="group" labelled by its label. A multiple select’s listbox has aria-multiselectable="true".
• The clear button, the tag remove buttons and the chevron are out of the tab order; Backspace removes the last tag from the keyboard.
• An error is aria-invalid="true" on the trigger with the message in aria-describedby; the native select has no validation bubble while it is hidden, so validate in the application.

Keyboard

Platform features

Without JavaScript

@media (scripting: none) in select.css hides the trigger, the clear button, the chevron and the popup and shows the native <select>, styled as the Tier 0 select below: the platform’s picker, keyboard and form submission. With scripting the native select is hidden and the owned field works on it.

Server rendering

Render the chosen option’s label in the value part, aria-expanded as false, an empty listbox and a closed popup. The register module is safe to import on the server.

Before hydration

Before the behavior loads, the field shows the server’s label and nothing opens. The registration attaches no per-root state, so the first interaction after hydration creates the controller and renders the options.

Styling

control.css draws the field: border, hover, focus halo, sizes (data-size), status (data-status), the clear and chevron icon masks, the popup surface, the option rows, the group labels and the check mark. select.css adds the value, the placeholder and the tags, hands the field to the native select without scripting, and styles the Tier 0 select. The tokens of control.css and select.css:

State selectors the stylesheet targets, all from the platform or ARIA: ::checkmark, ::picker(select), ::picker-icon, ::placeholder, :checked, :dir(rtl), :disabled, :empty, :focus-visible, :focus-within, :hover, :open, :placeholder-shown, :popover-open, :user-invalid, [aria-disabled="true"], [aria-expanded="true"], [aria-invalid="true"], [hidden], [multiple], [popover], [role="listbox"], [role="option"], [size].

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

Compatibility notes

Popover is Baseline 2024; CSS anchor positioning (Chrome 125, Safari 26) places the popup under the field, and without it the popover popup is centered in the top layer. :has() and @media (scripting) are Baseline 2023. The owned field is drawn by the stylesheet, so it looks the same in Chromium, WebKit and Gecko; the customizable select only affects the Tier 0 select.

Examples

Groups

Each <optgroup label> of the native select becomes a role="group" list with a label in the popup. A select without a placeholder option opens on its chosen option.

<label id="office-label" for="office-native">Office</label>
<div id="office" data-slean="select">
	<select id="office-native" name="office" data-slean-part="native">
		<optgroup label="Europe">
			<option value="berlin">Berlin</option>
			<option value="istanbul" selected>Istanbul</option>
			<option value="lisbon">Lisbon</option>
		</optgroup>
		<optgroup label="Asia">
			<option value="seoul">Seoul</option>
			<option value="tokyo">Tokyo</option>
		</optgroup>
	</select>
	<button type="button" role="combobox" aria-haspopup="listbox" aria-expanded="false"
		aria-controls="office-list" aria-labelledby="office-label" data-slean-part="trigger">
		<span data-slean-part="value">Istanbul</span>
	</button>
	<span data-slean-part="toggle" aria-hidden="true"></span>
	<div popover="manual" data-slean-part="popup">
		<!-- The behavior renders one role="group" with a group-label per <optgroup>. -->
		<ul id="office-list" role="listbox" aria-labelledby="office-label"></ul>
	</div>
</div>

Multiple

A <select multiple> shows the chosen options as tags inside the field. The popup stays open while options are toggled; a tag’s remove button drops that option and Backspace drops the last one. The trigger contains buttons, so it is a focusable <div role="combobox">. Here the application renders the tags from its bound value (data-slean-render="app").

<script lang="ts">
	const TEAMS = [
		{ value: 'design', label: 'Design' },
		{ value: 'engineering', label: 'Engineering' },
		{ value: 'research', label: 'Research' },
		{ value: 'support', label: 'Support' },
		{ value: 'sales', label: 'Sales' }
	];
	let teams = $state(['design', 'research']);
	const label = (value: string) => TEAMS.find((t) => t.value === value)?.label ?? '';
</script>

<label id="teams-label" for="teams-native">Teams</label>
<!-- data-slean-render="app": the application renders the tags; the behavior never writes them. -->
<div id="teams" data-slean="select" data-slean-render="app">
	<select id="teams-native" name="teams" multiple data-slean-part="native" bind:value={teams}>
		{#each TEAMS as t (t.value)}
			<option value={t.value}>{t.label}</option>
		{/each}
	</select>
	<!-- The trigger holds buttons, so it is a focusable div, not a <button>. -->
	<div role="combobox" tabindex="0" aria-haspopup="listbox" aria-expanded="false"
		aria-controls="teams-list" aria-labelledby="teams-label" data-slean-part="trigger">
		<span data-slean-part="value"
			>{#each teams as t (t)}<span data-slean-part="tag" data-slean-value={t}
					>{label(t)}<button type="button" tabindex="-1" aria-label="Remove {label(t)}"
						data-slean-part="remove"></button></span
				>{/each}</span
		>
		<span data-slean-part="placeholder">Select teams</span>
	</div>
	<button type="button" tabindex="-1" aria-label="Clear" data-slean-part="clear"></button>
	<span data-slean-part="toggle" aria-hidden="true"></span>
	<div popover="manual" data-slean-part="popup">
		<ul id="teams-list" role="listbox" aria-labelledby="teams-label"></ul>
	</div>
</div>

Sizes

data-size="sm" and data-size="lg" on the root change the height, the padding and, for the large field, the text size; they are the heights of every field of control.css.

<div id="size-sm" data-slean="select" data-size="sm">…</div>
<div id="size-md" data-slean="select">…</div>
<div id="size-lg" data-slean="select" data-size="lg">…</div>

Disabled and status

disabled on the native select and on the trigger disables the whole field. An error is data-status="error" on the root or aria-invalid="true" on the trigger, with the message related through aria-describedby; data-status="warning" is the warning border.

<!-- Disabled: disabled on the native select and on the trigger. -->
<div id="plan" data-slean="select">
	<select id="plan-native" name="plan" data-slean-part="native" disabled>…</select>
	<button type="button" role="combobox" … data-slean-part="trigger" disabled>…</button>
	…
</div>

<!-- Error: data-status="error" on the root (or aria-invalid="true" on the trigger), with the
     message related through aria-describedby. -->
<div id="region" data-slean="select" data-status="error">
	…
	<button type="button" role="combobox" … aria-invalid="true"
		aria-describedby="region-error" data-slean-part="trigger">…</button>
	…
</div>
<p id="region-error">Choose a region.</p>

Styled native select

A bare <select data-slean="select"> is the Tier 0 path: no behavior is registered for it and select.css styles the closed box, with the customizable select (appearance: base-select) drawing the picker where the browser has it. It is also how the native part of an owned select looks without JavaScript. Use it where the platform’s picker is wanted, for example in a dense toolbar.

<!-- The Tier 0 styled native select: no behavior, no JavaScript. -->
<label for="size">Font size</label>
<select id="size" name="size" data-slean="select" data-size="sm">
	<option>12</option>
	<option selected>14</option>
	<option>16</option>
</select>

Testing

• packages/primitives/src/select/contract.md the test cases of the contract: tests/select.test.ts (happy-dom) and a Playwright spec on the playground’s /primitives/select page
• apps/playground/src/routes/primitives/select/+page.svelte the playground fixtures: single with a placeholder, groups, multiple with tags, small and disabled, the Tier 0 native select
• apps/playground/tests/primitives/nested.spec.ts a select inside a modal dialog: the popup above the dialog, a click on an option, Escape closing the popup before the dialog
• apps/playground/tests/stress/memory.spec.ts 200 open/close cycles: heap, DOM nodes and listeners back at baseline, one scoped listener per open
• fixtures/select-only consumer build: only the select registration, lazyState and the popup session ship; tabs, menu, listbox, combobox and the calendar are absent
• apps/playground/tests/primitives/forms.spec.ts Playwright: keyboard, form values, :user-invalid, names and descriptions, axe
• packages/styles/tests static checks of the stylesheet (layers, tokens, specificity, dark parity)
• apps/playground/tests/primitives/a11y.spec.ts axe on every playground page and on open dialog, popover and menu states

Source

• packages/primitives/src/select/contract.md the contract in prose: semantics, keyboard, focus, ARIA, SSR, JS-disabled behavior
• packages/primitives/src/select/contract.ts typed constants: name, tier, base, parts, options, events
• packages/primitives/src/select/behavior.ts the behavior definition, openSelect(), closeSelect(), chooseOption(), clearSelect(), renderSelectOptions()
• packages/primitives/src/select/register.ts the registration module, the only side effect
• packages/primitives/src/select/validate.ts development validation messages
• packages/styles/css/control.css the control shell shared with the combobox and the date picker
• packages/styles/css/select.css the optional stylesheet