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
<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.
<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.
| Prop | Type | Default |
|---|---|---|
type * | 'single' | 'multiple' One value (string) or several (string[]). | – |
value bind | string | string[] The selected value(s). | – |
open bind | boolean 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 attributesThe field that opens the list. Put the selected label inside it.
| Prop | Type | Default |
|---|---|---|
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 bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="select-trigger" | Always present. |
data-state | "open" or "closed". |
data-placeholder | Present while nothing is selected. |
data-size / data-variant | The current size and variant. |
Select.Content
renders<div role="listbox"> and accepts its attributesThe popover with the options. Rendered in a portal.
| Prop | Type | Default |
|---|---|---|
sideOffset | number Gap between trigger and list in px. | 6 |
portalProps | PortalProps Passed to the portal, for example to render somewhere else. | – |
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-slot="select-content" | Always present. |
data-side | Where the list opened: top, bottom, left or right. |
Select.Item
renders<div role="option"> and accepts its attributesOne option. Shows a primary check when selected.
| Prop | Type | Default |
|---|---|---|
value * | string The value it selects. | – |
label | string Text shown and used for typeahead. Defaults to value. | – |
disabled | boolean Disables this option. | false |
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
| Data attribute | Meaning |
|---|---|
data-highlighted | Present while it has keyboard or pointer focus. |
data-selected | Present when selected. |
data-disabled | Present when disabled. |
Select.Group
renders<div role="group"> and accepts its attributesGroups related items.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Select.Label
renders<div> and accepts its attributesMuted heading for a group.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Select.GroupHeading
renders<div> and accepts its attributesLike Select.Label, but wired to the group with aria-labelledby.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |
Select.Separator
renders<div> and accepts its attributesHairline between groups.
| Prop | Type | Default |
|---|---|---|
ref bind | HTMLElement | null The rendered element. | – |
class | ClassValue Merged with the default classes; yours win. | – |