Skip to content
Statix Design System

Forms

Select

Pick one option from a list. The trigger looks like an Input; the list opens in a popover. Use NativeSelect when you need the browser picker.

import * as Select from '@statix/ui/select';

Playground

Controls
<Select.Root type="single" bind:value>
	<Select.Trigger>{value || 'Choose a time'}</Select.Trigger>
	<Select.Content>
		<Select.Item value="01:00" label="01:00" />
		<Select.Item value="03:10" label="03:10" />
	</Select.Content>
</Select.Root>

Examples

Basic

Bind the value and render the matching label inside the trigger.

<script lang="ts">
	import { Label } from '@statix/ui/label';
	import * as Select from '@statix/ui/select';

	const times = [
		{ value: '01:00', label: '01:00' },
		{ value: '03:10', label: '03:10 (recommended)' },
		{ value: '05:00', label: '05:00' },
		{ value: '23:00', label: '23:00' }
	];

	let value = $state('03:10');
	const selected = $derived(times.find((t) => t.value === value)?.label ?? 'Choose a time');
</script>

<div class="flex w-full max-w-xs flex-col gap-2">
	<Label for="backup-time">Daily backup at</Label>
	<Select.Root type="single" name="backupTime" bind:value>
		<Select.Trigger id="backup-time" class="w-full">{selected}</Select.Trigger>
		<Select.Content>
			{#each times as time (time.value)}
				<Select.Item value={time.value} label={time.label} />
			{/each}
		</Select.Content>
	</Select.Root>
</div>

Groups

Group options with SelectGroup and SelectLabel, split groups with SelectSeparator.

<script lang="ts">
	import { Label } from '@statix/ui/label';
	import * as Select from '@statix/ui/select';

	const mailboxes = [
		{ value: 'anna', label: 'anna@yoga-berger.de' },
		{ value: 'kurse', label: 'kurse@yoga-berger.de' }
	];
	const external = [{ value: 'gmail', label: 'anna.berger@gmail.com' }];

	let value = $state('');
	const selected = $derived(
		[...mailboxes, ...external].find((m) => m.value === value)?.label ?? 'Choose a mailbox'
	);
</script>

<div class="flex w-full max-w-xs flex-col gap-2">
	<Label for="forward-to">Forward info@ to</Label>
	<Select.Root type="single" bind:value>
		<Select.Trigger id="forward-to" class="w-full">{selected}</Select.Trigger>
		<Select.Content>
			<Select.Group>
				<Select.Label>Your mailboxes</Select.Label>
				{#each mailboxes as mailbox (mailbox.value)}
					<Select.Item value={mailbox.value} label={mailbox.label} />
				{/each}
			</Select.Group>
			<Select.Separator />
			<Select.Group>
				<Select.Label>Other addresses</Select.Label>
				{#each external as mailbox (mailbox.value)}
					<Select.Item value={mailbox.value} label={mailbox.label} />
				{/each}
			</Select.Group>
		</Select.Content>
	</Select.Root>
</div>

In a form, with an error

Inside a Field, set aria-invalid on the trigger and show a FieldError.

Your contract for yoga-berger.de ends on 31 March 2027.

<script lang="ts">
	import { Button } from '@statix/ui/button';
	import * as Field from '@statix/ui/field';
	import * as Select from '@statix/ui/select';

	const reasons = [
		{ value: 'price', label: 'Too expensive' },
		{ value: 'moving', label: 'Moving to another provider' },
		{ value: 'closing', label: 'Closing the business' },
		{ value: 'other', label: 'Something else' }
	];

	let value = $state('');
	let submitted = $state(false);
	const invalid = $derived(submitted && !value);
	const selected = $derived(reasons.find((r) => r.value === value)?.label ?? 'Choose a reason');
</script>

<form
	class="w-full max-w-sm"
	onsubmit={(e) => {
		e.preventDefault();
		submitted = true;
	}}
>
	<Field.Group>
		<Field.Field data-invalid={invalid || undefined}>
			<Field.Label for="cancel-reason">Why are you cancelling?</Field.Label>
			<Select.Root type="single" bind:value>
				<Select.Trigger
					id="cancel-reason"
					class="w-full"
					aria-invalid={invalid || undefined}
					aria-describedby="cancel-reason-msg"
				>
					{selected}
				</Select.Trigger>
				<Select.Content>
					{#each reasons as reason (reason.value)}
						<Select.Item value={reason.value} label={reason.label} />
					{/each}
				</Select.Content>
			</Select.Root>
			{#if invalid}
				<Field.Error id="cancel-reason-msg">Choose a reason to continue.</Field.Error>
			{:else}
				<Field.Description id="cancel-reason-msg">
					Your contract for yoga-berger.de ends on 31 March 2027.
				</Field.Description>
			{/if}
		</Field.Field>
		<div>
			<Button type="submit" variant="dark">Continue</Button>
		</div>
	</Field.Group>
</form>

Sizes and pill

Trigger sizes match Input: sm 36px, md 44px, lg 52px. pill is fully rounded, for filters in toolbars.

<script lang="ts">
	import * as Select from '@statix/ui/select';

	const sizes = ['sm', 'md', 'lg'] as const;
	const periods = [
		{ value: '7', label: 'Last 7 days' },
		{ value: '30', label: 'Last 30 days' },
		{ value: '90', label: 'Last 90 days' }
	];
	let value = $state('30');
	const selected = $derived(periods.find((p) => p.value === value)?.label);
</script>

<div class="flex flex-wrap items-center gap-3">
	{#each sizes as size (size)}
		<Select.Root type="single" bind:value>
			<Select.Trigger {size} aria-label="Period, size {size}">{selected}</Select.Trigger>
			<Select.Content>
				{#each periods as period (period.value)}
					<Select.Item value={period.value} label={period.label} />
				{/each}
			</Select.Content>
		</Select.Root>
	{/each}
	<Select.Root type="single" bind:value>
		<Select.Trigger variant="pill" aria-label="Period, pill">{selected}</Select.Trigger>
		<Select.Content>
			{#each periods as period (period.value)}
				<Select.Item value={period.value} label={period.label} />
			{/each}
		</Select.Content>
	</Select.Root>
</div>

Disabled

Disable single items or the whole select.

<script lang="ts">
	import { Label } from '@statix/ui/label';
	import * as Select from '@statix/ui/select';

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

<div class="flex w-full max-w-xs flex-col gap-4">
	<div class="flex flex-col gap-2">
		<Label for="php-version">PHP version</Label>
		<Select.Root type="single" bind:value>
			<Select.Trigger id="php-version" class="w-full">PHP {value}</Select.Trigger>
			<Select.Content>
				<Select.Item value="8.3" label="PHP 8.3" />
				<Select.Item value="8.2" label="PHP 8.2" />
				<Select.Item value="7.4" label="PHP 7.4 (no longer supported)" disabled />
			</Select.Content>
		</Select.Root>
	</div>
	<div class="flex flex-col gap-2">
		<Label for="data-center">Data center</Label>
		<Select.Root type="single" value="fra" disabled>
			<Select.Trigger id="data-center" class="w-full">Frankfurt, Germany</Select.Trigger>
			<Select.Content>
				<Select.Item value="fra" label="Frankfurt, Germany" />
			</Select.Content>
		</Select.Root>
	</div>
</div>

Guidelines

Do

  • Use Select for six or more options, or when space is tight.
  • Show a placeholder like "Choose a reason" until something is picked.
  • Sort options in a way people expect: by time, by size or alphabetically.

Don't

  • Don't use Select for two or three options. Show them as a RadioGroup.
  • Don't put actions such as "Add mailbox" in the list. Use DropdownMenu.

Accessibility

  • The trigger has role="combobox" and aria-expanded; the list has role="listbox" with role="option" items.
  • Enter, Space or the arrow keys open it. Arrow keys move, Enter selects, Escape closes, typing jumps to a match.
  • Label the trigger with <Label for> pointing at its id, or aria-label.
  • Pass name on the root to submit the value with a native form.

API reference

Select.Root

Holds the state. Renders no element.

PropTypeDefault
type * 'single' | 'multiple'

One value (string) or several (string[]).

–
value bindstring | string[]

The selected value(s).

–
open bindboolean

Whether the list is open.

false
onValueChange (value) => void

Called when the selection changes.

–
disabled boolean

Disables the select.

false
name string

Name of the hidden input for form submission.

–
required boolean

Marks it as required in a form.

false

Select.Trigger

renders <button role="combobox"> and accepts its attributes

The field that opens the list. Put the selected label inside it.

PropTypeDefault
variant 'default' | 'pill'

default has 16px corners like Input. pill is fully rounded.

'default'
size 'sm' | 'md' | 'lg'

Height: 36, 44 or 52px. default is an alias of md.

'md'
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="select-trigger"Always present.
data-state"open" or "closed".
data-placeholderPresent while nothing is selected.
data-size / data-variantThe current size and variant.

Select.Content

renders <div role="listbox"> and accepts its attributes

The popover with the options. Rendered in a portal.

PropTypeDefault
sideOffset number

Gap between trigger and list in px.

6
portalProps PortalProps

Passed to the portal, for example to render somewhere else.

–
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-slot="select-content"Always present.
data-sideWhere the list opened: top, bottom, left or right.

Select.Item

renders <div role="option"> and accepts its attributes

One option. Shows a primary check when selected.

PropTypeDefault
value * string

The value it selects.

–
label string

Text shown and used for typeahead. Defaults to value.

–
disabled boolean

Disables this option.

false
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–
Data attributeMeaning
data-highlightedPresent while it has keyboard or pointer focus.
data-selectedPresent when selected.
data-disabledPresent when disabled.

Select.Group

renders <div role="group"> and accepts its attributes

Groups related items.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Select.Label

renders <div> and accepts its attributes

Muted heading for a group.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Select.GroupHeading

renders <div> and accepts its attributes

Like Select.Label, but wired to the group with aria-labelledby.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–

Select.Separator

renders <div> and accepts its attributes

Hairline between groups.

PropTypeDefault
ref bindHTMLElement | null

The rendered element.

–
class ClassValue

Merged with the default classes; yours win.

–