Skip to content

Components

Select

A form field that picks one value from a list of options, defined as data. It follows the select-only combobox pattern, so keyboard and screen reader users get the behaviour of a native select.

Live demo

This is the Tailwind wrapper from the recipe below, running. Pick a country and watch the bound value change.

value = null

Usage

An option is { value, label, disabled? }. A value with no matching option shows the placeholder and marks nothing selected; the component does not reset it.

<script>
	import { Select } from '@frostycle/rime/select';

	let country = $state(null);

	const items = [
		{ value: 'id', label: 'Indonesia' },
		{ value: 'th', label: 'Thailand' },
		{ type: 'separator' },
		{
			type: 'group',
			label: 'Coming soon',
			items: [{ value: 'vn', label: 'Vietnam', disabled: true }]
		}
	];
</script>

<label for="country">Country</label>
<Select id="country" {items} bind:value={country} name="country" placeholder="Choose a country" />

Labelling

Every select needs a <label for> pointing at its id; a combobox does not take its name from its text. Use <label for> rather than a wrapping <label>: a wrapping label's text includes the trigger's own text, which would put the current value into the list's accessible name. Clicking the label focuses the trigger without opening the list. A custom trigger snippet must keep the spread id.

The list takes its name from the label text when it opens. Naming a custom trigger only with aria-label or aria-labelledby leaves the list unnamed, so keep a <label for> even then.

Props

PropTypeNotes
items(T | SelectSeparator | SelectGroup<T>)[]Required. T extends SelectOption, so extra fields such as an icon flow into the option snippet.
valuestring | nullBindable. null means nothing is selected. Default null.
onchange(value: string | null) => voidCalled when the user picks a different value.
idstringThe trigger's id, so <label for> names the field. Default a generated id.
namestringRenders a hidden input carrying the value, empty when null.
placeholderstringTrigger text while the value is null.
placementPlacementFrom @floating-ui/dom. Default bottom-start.
disabledbooleanDisables the trigger, closes the list if it is open, and renders no hidden input.
transitionbooleanKeeps the popup mounted through its CSS transition, as on the date pickers. Default false.
classes{ trigger, popup, option, separator, group, groupLabel }Classes for default-rendered elements.

Snippets

All optional. Spread each props onto your element.

  • trigger

    props, open, selected

    selected is the selected option, or null.

  • popup

    props, content

    Render content for the default body.

  • option

    option, props, selected, highlighted, disabled

  • separator

    props

    Renders with role="none" inside the list, since a listbox may contain only options and groups.

  • groupLabel

    label, props

Separators render with role="none" inside the list, since a listbox may contain only options and groups.

Keyboard

Focus stays on the trigger; the highlighted option is announced through aria-activedescendant. Disabled options are skipped, and hovering an enabled option highlights it, so pointer and keyboard share one highlight.

Enter, Space, Down, Up on the trigger
Open the list
Home, End on the trigger
Open with the first or last enabled option highlighted
Printable characters on the trigger
Open at the first matching enabled option
Down, Up
Move between enabled options, stopping at the ends
Home, End
Go to the first or last enabled option
Page Down, Page Up
Move ten enabled options
Printable characters
Jump to the next enabled option starting with what was typed. Typed text resets after 500 ms, repeating one character cycles through matches, and Space counts as typed text while it is being collected
Enter, Space
Select the highlighted option and close
Tab
Select the highlighted option, close, and let focus move on
Escape
Close without changing the value

State attributes

Style state with data-* attributes rather than props. They are present or absent, with no value.

ElementAttributes
Triggerdata-open, data-disabled, data-placeholder, data-hover, data-focus, data-active
Popupdata-open, plus data-closed, data-enter and data-leave with transition
Optiondata-highlighted, data-selected, data-disabled

Forms

With name, a hidden input carries the value, empty when it is null. A form reset restores the value from when the component mounted. required and browser validation are not supported yet.

Tailwind recipe

The library ships no Tailwind classes, so there is nothing to configure or override. Copy this wrapper into your project and own it. It needs Tailwind CSS v4, whose bare data-selected: variants it uses; in v3 write data-[selected]:.

import type { SelectClasses } from '@frostycle/rime/select';

export const selectClasses: SelectClasses = {
	trigger:
		'min-w-48 rounded-md border border-gray-300 bg-white px-3 py-2 text-start text-sm text-gray-900 data-hover:bg-gray-50 data-focus:outline-2 data-focus:outline-offset-2 data-focus:outline-blue-600 data-open:border-blue-600 data-placeholder:text-gray-500 data-disabled:opacity-50 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100 dark:data-placeholder:text-gray-400 dark:data-hover:bg-gray-700',
	popup:
		'min-w-48 rounded-lg border border-gray-200 bg-white p-1.5 text-sm text-gray-900 shadow-lg transition duration-150 ease-out outline-none data-closed:-translate-y-1 data-closed:opacity-0 motion-reduce:transition-none dark:border-gray-700 dark:bg-gray-800 dark:text-gray-100',
	option:
		'block w-full rounded-md px-2.5 py-1.5 text-start data-highlighted:bg-gray-100 data-selected:font-semibold data-disabled:opacity-50 dark:data-highlighted:bg-gray-700',
	separator: 'mx-1 my-1.5 h-px bg-gray-200 dark:bg-gray-700',
	groupLabel: 'px-2.5 pt-1.5 pb-1 text-xs font-semibold text-gray-500 dark:text-gray-400'
};
<script lang="ts" generics="T extends SelectOption">
	import { Select, type SelectOption, type SelectProps } from '@frostycle/rime/select';
	import { selectClasses } from './select-classes.js';

	let { value = $bindable(null), ...props }: SelectProps<T> = $props();
</script>

<Select transition classes={selectClasses} bind:value {...props} />
<AppSelect id="country" {items} bind:value={country} name="country" />

Behaviour to plan for

Disabling an open select closes it and disables the trigger, so focus falls to <body>. Move focus yourself if you disable a select while it is in use.