Skip to content

Select

A select. Render Select.Trigger, Select.Content, Select.Viewport, and Select.Items inside it. Inside a Field it takes disabled and required from there.

Built on bits-ui Select.

<Field class="flex flex-col gap-1">
<Label>Size</Label>
<Select bind:value items={sizes}>
<Select.Trigger>
<Select.Value placeholder="Pick a size" />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Items />
</Select.Viewport>
</Select.Content>
</Select>
</Field>
  • Composed from parts, so the trigger, the panel, and each item are yours to arrange.
  • One value, bindable. items is the single source of truth for the options: it gives the closed trigger its label, drives typeahead while the list is closed, and Select.Items renders it.
  • Keyboard navigation, typeahead, and the WAI-ARIA listbox pattern, via bits-ui.
  • Select.Trigger takes state from an enclosing Field, or directly. error sets aria-invalid="true" and a red border. warn sets a warning border. Both come from the same input component class as Input.
  • The panel floats in a portal, positioned to the trigger, and scrolls when the list is long.
  • One value at a time. For several, MultiSelect takes the same parts with a string[] value.

Every part is a property on Select. Content is the floating panel, portaled to the body. Viewport is the scrolling region, and Content should contain one. Items renders every entry of items as a Select.Item, and renders no element of its own. Group and GroupHeading are optional.

<Select>
<Select.Trigger>
<Select.Value />
</Select.Trigger>
<Select.Content>
<Select.ScrollUpButton />
<Select.Viewport>
<Select.Items />
</Select.Viewport>
<Select.ScrollDownButton />
</Select.Content>
</Select>

To arrange items by hand, for example under group headings, compose Select.Item instead. items is still required on Select for the closed label.

<Select items={options}>
<Select.Trigger>
<Select.Value />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Item />
<Select.Group>
<Select.GroupHeading />
<Select.Item />
</Select.Group>
</Select.Viewport>
<Select.ScrollDownButton />
</Select.Content>
</Select>

bind:value on the root. Pass the options as items and render them with <Select.Items />.

value: md

Code
TwoWay.svelte
<script lang="ts">
import { Field, Label, Select } from "@viamrobotics/prime-ui";
const sizes = [
{ value: "sm", label: "Small" },
{ value: "md", label: "Medium" },
{ value: "lg", label: "Large" },
];
let size = $state("md");
</script>
<div class="not-content">
<Field class="flex max-w-xs flex-col gap-1">
<Label>Size</Label>
<Select bind:value={size} items={sizes} name="size">
<Select.Trigger>
<Select.Value placeholder="Pick a size" />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Items />
</Select.Viewport>
</Select.Content>
</Select>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{size}</code></p>
</div>

Pass bind:value a getter and a setter. State & binding explains both modes.

EU Central is declined by the setter, so picking it changes nothing.

value: us-east

Code
Controlled.svelte
<script lang="ts">
import { Field, Hint, Label, Select } from "@viamrobotics/prime-ui";
const regions = [
{ value: "us-east", label: "US East" },
{ value: "us-west", label: "US West" },
{ value: "eu-central", label: "EU Central (no capacity)" },
];
let region = $state("us-east");
</script>
<div class="not-content">
<Field class="flex max-w-xs flex-col gap-1">
<Label>Region</Label>
<Select
items={regions}
bind:value={
() => region,
(next) => {
if (next !== "eu-central") region = next;
}
}
>
<Select.Trigger>
<Select.Value placeholder="Pick a region" />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Items />
</Select.Viewport>
</Select.Content>
</Select>
<Hint>EU Central is declined by the setter, so picking it changes nothing.</Hint>
</Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{region}</code></p>
</div>

Three ways turn items into rows. All three keep items on the root, which the closed trigger and typeahead read. The difference is who writes the loop.

Approach Use it when
<Select.Items /> Every option is its label plus a check when selected. The default, shown in the two-way example above.
Select.Items with a children snippet Every option shares one custom layout. The snippet receives { item, selected, highlighted }, with item the entry from items.
{#each} over Select.Item The rows need something items cannot carry: extra data per row, groups, scroll buttons, or rows that are not one-to-one with items.

Pass children to Select.Items. The snippet sees item as a SelectOption, so value, label, and disabled. A row that needs more data per entry is the by-hand loop below. The trigger’s chevron is an indicator snippet on Select.Trigger in the same way.

Code
CustomItem.svelte
<script lang="ts">
import { mdiUnfoldMoreVertical } from "@mdi/js";
import { Icon, Select } from "@viamrobotics/prime-ui";
const machines = [
{ value: "rover-1", label: "Rover 1" },
{ value: "rover-2", label: "Rover 2", disabled: true },
{ value: "arm-1", label: "Arm 1" },
];
let machine = $state("rover-1");
</script>
<div class="not-content max-w-xs">
<Select items={machines} bind:value={machine}>
<Select.Trigger class="w-64" aria-label="Machine">
<Select.Value placeholder="Pick a machine" />
{#snippet indicator()}
<Icon icon={mdiUnfoldMoreVertical} size="base" class="shrink-0 text-subtle-2" />
{/snippet}
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Items>
{#snippet children({ item, selected })}
<span class={{ "font-medium": selected }}>{item.label}</span>
<code class="text-xs text-subtle-2">{item.value}</code>
{/snippet}
</Select.Items>
</Select.Viewport>
</Select.Content>
</Select>
</div>

Loop over your own data and render a Select.Item per entry. Select.Item takes the same children snippet without item, since the loop already has the entry in scope. items stays on the root so the closed trigger can show the selected label.

Code
ManualItems.svelte
<script lang="ts">
import { Select } from "@viamrobotics/prime-ui";
const sizes = [
{ value: "sm", label: "Small", hint: "fits a 2 inch wheel" },
{ value: "md", label: "Medium", hint: "fits a 4 inch wheel" },
{ value: "lg", label: "Large", hint: "fits a 6 inch wheel" },
];
let size = $state("md");
</script>
<div class="not-content max-w-xs">
<Select items={sizes} bind:value={size}>
<Select.Trigger class="w-64" aria-label="Size">
<Select.Value placeholder="Pick a size" />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
{#each sizes as { value, label, hint } (value)}
<Select.Item {value} {label}>
{#snippet children({ selected })}
<span class={{ "font-medium": selected }}>{label}</span>
<span class="text-xs text-subtle-2">{hint}</span>
{/snippet}
</Select.Item>
{/each}
</Select.Viewport>
</Select.Content>
</Select>
</div>

The by-hand form is also how you add structure. Wrap related items in Select.Group with a Select.GroupHeading. For a list taller than the panel, put Select.ScrollUpButton and Select.ScrollDownButton around the viewport. They appear only when there is more to scroll in that direction.

value: none

Code
Grouped.svelte
<script lang="ts">
import { Select } from "@viamrobotics/prime-ui";
const groups = [
{
heading: "Planet Express",
items: [
{ value: "fry", label: "Philip J. Fry" },
{ value: "leela", label: "Turanga Leela" },
{ value: "bender", label: "Bender Bending Rodriguez" },
{ value: "farnsworth", label: "Hubert J. Farnsworth" },
{ value: "hermes", label: "Hermes Conrad" },
{ value: "amy", label: "Amy Wong" },
{ value: "zoidberg", label: "Zoidberg" },
],
},
{
heading: "Robot Mafia",
items: [
{ value: "donbot", label: "Donbot" },
{ value: "clamps", label: "Clamps" },
{ value: "joey", label: "Joey Mousepad" },
],
},
{
heading: "DOOP",
items: [
{ value: "zapp", label: "Zapp Brannigan" },
{ value: "kif", label: "Kif Kroker" },
],
},
{
heading: "Others",
items: [
{ value: "mom", label: "Mom" },
{ value: "wernstrom", label: "Professor Ogden Wernstrom" },
{ value: "calculon", label: "Calculon" },
{ value: "morbo", label: "Morbo" },
],
},
];
// The closed trigger resolves its label from this flat list.
const characters = groups.flatMap((group) => group.items);
let character = $state("");
</script>
<div class="not-content">
<div class="max-w-xs">
<Select items={characters} bind:value={character}>
<Select.Trigger class="w-64" aria-label="Character">
<Select.Value placeholder="Pick a character" />
</Select.Trigger>
<Select.Content>
<Select.ScrollUpButton />
<Select.Viewport>
{#each groups as group (group.heading)}
<Select.Group>
<Select.GroupHeading>{group.heading}</Select.GroupHeading>
{#each group.items as item (item.value)}
<Select.Item value={item.value} label={item.label} />
{/each}
</Select.Group>
{/each}
</Select.Viewport>
<Select.ScrollDownButton />
</Select.Content>
</Select>
</div>
<p class="mt-3 text-sm text-subtle-2">value: <code>{character || "none"}</code></p>
</div>

Select.Content takes side and align to place the panel, and sideOffset and alignOffset to nudge it. The API table lists each option and its default. The panel flips to the other side when there is no room.

Code
Placed.svelte
<script lang="ts">
import { Select } from "@viamrobotics/prime-ui";
const sizes = [
{ value: "sm", label: "Small" },
{ value: "md", label: "Medium" },
{ value: "lg", label: "Large" },
];
let size = $state("md");
</script>
<div class="not-content max-w-xs pt-32">
<Select items={sizes} bind:value={size}>
<Select.Trigger class="w-64" aria-label="Size">
<Select.Value placeholder="Pick a size" />
</Select.Trigger>
<Select.Content side="top" align="end">
<Select.Viewport>
<Select.Items />
</Select.Viewport>
</Select.Content>
</Select>
</div>

Placeholder, with a disabled item

Error

Disabled

A prime-core Select was a native <select> with <option> children and an onchange. The same control here is items plus the six parts, and the value comes through bind:value instead of the event.

<!-- before -->
<Select value={method} onchange={(event) => (method = event.currentTarget.value)}>
{#each methods as method (method)}
<option>{method}</option>
{/each}
</Select>
<!-- after -->
<Select items={methods.map((value) => ({ value, label: value }))} bind:value={method}>
<Select.Trigger class="w-full">
<Select.Value placeholder="Pick a method" />
</Select.Trigger>
<Select.Content>
<Select.Viewport>
<Select.Items />
</Select.Viewport>
</Select.Content>
</Select>

Select.Trigger has no width of its own, so the class that sat on the old wrapper goes there. A state that sat on the old <select> goes on the trigger too, or on an enclosing Field.

Every part that renders an element takes class on that element. Select.Trigger carries no width of its own, so set one with a class such as w-64 or w-full. Focus shows as the same 2px ring every prime control uses. Select and Select.Items render no element, so they take no class, and Select takes no event handlers. onfocus, onblur, onkeydown, and the rest go on Select.Trigger, the real <button>. The panel width follows the trigger through --bits-select-anchor-width. Its max height follows --bits-select-content-available-height. bits-ui sets both variables. bits-ui also sets the data attributes in the table below. Select.Content wears z-popover; see z layers.

Part Attribute Value
Trigger data-state open or closed
Trigger data-disabled present when disabled
Trigger data-placeholder present while nothing is selected
Trigger aria-invalid true when state is error
Trigger data-field-state info, warn, or error, set by prime
Value data-placeholder present while nothing is selected
Content data-state open or closed
Content data-side the resolved side of the trigger
Content data-align the resolved alignment
Item data-selected present when selected
Item data-highlighted present under the pointer or keys
Item data-disabled present when disabled
Item data-value the item’s value

With focus on the trigger:

KeyAction
Enter / Space / ArrowDown / ArrowUpOpens the panel.
Printable charactersSelects the next item from items matching the text, without opening.

With the panel open:

KeyAction
ArrowDown / ArrowUpHighlights the next or previous item.
Home / EndHighlights the first or last item.
PageDown / PageUpHighlights the item a page away.
Enter / SpaceSelects the highlighted item and closes.
Alt + ArrowUpSelects the highlighted item and closes.
Printable charactersTypeahead: highlights the next item matching the text.
EscapeCloses without changing the value.
TabCloses and moves focus on.
PropTypeDefaultDescription
itemsSelectOption[]The options, and the single source of truth for the select. [Select.Items](./SelectItems.svelte) renders one option per entry. The closed trigger shows the selected entry's label. Typing while the list is closed selects the matching entry without opening it.
bind:valuestringThe selected value. Two-way bindable.
namestringName for form submission.
disabledbooleanDisable the select. Defaults to the enclosing field's disabled.
requiredbooleanMake selection required. Defaults to the enclosing field's required.
allowDeselectbooleanfalseAllow clicking the selected item again to clear it.
childrenSnippetThe Select.* parts.

Select.Content

The floating panel of a Select, portaled to the body. Render a Select.Viewport inside it.

PropTypeDefaultDescription
idstringElement id. null is not accepted.
dir'ltr' | 'rtl'Text direction of the panel. auto is not accepted, because positioning needs a concrete direction.
side'top' | 'right' | 'bottom' | 'left''bottom'Which side of the trigger the panel opens on.
align'start' | 'center' | 'end''start'Alignment of the panel along the trigger's edge.
sideOffsetnumber4Gap in pixels between the trigger and the panel.
alignOffsetnumber0Shift in pixels along the alignment axis.
portalPortalTargettrueWhere the panel renders: true at the end of <body>, false in place, or inside an element or the first match of a CSS selector.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

Select.Group

Groups related Select.Items, optionally labeled by a Select.GroupHeading.

PropTypeDefaultDescription
idstringElement id. null is not accepted.

Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.

Select.GroupHeading

A non-selectable heading for a Select.Group.

Takes extraClasses, children, ...restProps }: Props as its props.

Select.Item

A selectable option within a Select.Content.

By default it renders its label (or value) plus a check when selected.

Pass a children snippet to render custom content:

<Select.Item value="sm" label="Small">
{#snippet children({ selected })}
<span class:font-medium={selected}>Small</span>
{/snippet}
</Select.Item>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
valuestringThe value this item selects when chosen.
labelstringText shown for the item and matched by typeahead. Falls back to value.
disabledbooleanfalsePrevent the item from being selected.
childrenSnippet<[{ selected: boolean; highlighted: boolean }]>Replaces the label and check. Receives { selected, highlighted }.

Plus everything in Omit<HTMLAttributes<HTMLDivElement>, 'children'>, spread onto the element.

Select.Items

Renders the items of the enclosing Select as Select.Items. Composing Select.Item by hand still works.

Takes content }: Props as its props.

Select.ScrollDownButton

A button that scrolls a long Select.Content down.

Appears only when items are hidden below the visible list. Children replace the default chevron.

Takes extraClasses, children, ...restProps }: Props as its props.

Select.ScrollUpButton

A button that scrolls a long Select.Content up.

Appears only when items are hidden above the visible list. Children replace the default chevron.

Takes extraClasses, children, ...restProps }: Props as its props.

Select.Trigger

The button that opens a Select. Inside a Field it takes its id (the field’s controlId), state, and aria-describedby from there. An error state sets aria-invalid and the error border, and warn the warning border, the same input class from @viamrobotics/tailwind-config an Input wears. Pair it with a Hint or a Field.StateIcon that says what is wrong, since the border color alone is not a signal everyone can see.

Add a Select.Value child to show the current selection.

A trailing chevron is rendered by default. Pass an indicator snippet to replace it:

<script>
import { mdiChevronDown } from '@mdi/js';
</script>
<Select.Trigger>
<Select.Value placeholder="Pick one" />
{#snippet indicator()}
<Icon icon={mdiChevronDown} size="lg" />
{/snippet}
</Select.Trigger>
PropTypeDefaultDescription
indicatorSnippetReplaces the trailing chevron.
stateFieldStateContextual state. Defaults to the enclosing field's state.

Plus everything in HTMLButtonAttributes, spread onto the element.

Select.Value

Renders the selected option’s label inside a Select.Trigger, falling back to placeholder.

Takes extraClasses, ...restProps }: Props as its props.

Select.Viewport

The scrollable region inside a Select.Content that holds the items.

Takes extraClasses, children, ...restProps }: Props as its props.