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.itemsis the single source of truth for the options: it gives the closed trigger its label, drives typeahead while the list is closed, andSelect.Itemsrenders it. - Keyboard navigation, typeahead, and the WAI-ARIA listbox pattern, via bits-ui.
Select.Triggertakesstatefrom an enclosingField, or directly.errorsetsaria-invalid="true"and a red border.warnsets a warning border. Both come from the sameinputcomponent class asInput.- The panel floats in a portal, positioned to the trigger, and scrolls when the list is long.
- One value at a time. For several,
MultiSelecttakes the same parts with astring[]value.
Anatomy
Section titled “Anatomy”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>Two-way binding
Section titled “Two-way binding”bind:value on the root. Pass the options as items and render them with <Select.Items />.
value: md
Code
<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>Fully controlled
Section titled “Fully controlled”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
<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>Rendering the options
Section titled “Rendering the options”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. |
One snippet for every option
Section titled “One snippet for every option”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
<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>Items by hand
Section titled “Items by hand”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
<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>Groups and scroll buttons
Section titled “Groups and scroll buttons”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
<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>Placement
Section titled “Placement”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
<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>States
Section titled “States”Placeholder, with a disabled item
Error
Disabled
Migrating from a native select
Section titled “Migrating from a native select”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.
Styling
Section titled “Styling”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 |
Keyboard
Section titled “Keyboard”With focus on the trigger:
| Key | Action |
|---|---|
| Enter / Space / ArrowDown / ArrowUp | Opens the panel. |
| Printable characters | Selects the next item from items matching the text, without opening. |
With the panel open:
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Highlights the next or previous item. |
| Home / End | Highlights the first or last item. |
| PageDown / PageUp | Highlights the item a page away. |
| Enter / Space | Selects the highlighted item and closes. |
| Alt + ArrowUp | Selects the highlighted item and closes. |
| Printable characters | Typeahead: highlights the next item matching the text. |
| Escape | Closes without changing the value. |
| Tab | Closes and moves focus on. |
| Prop | Type | Default | Description |
|---|---|---|---|
items | SelectOption[] | 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:value | string | The selected value. Two-way bindable. | |
name | string | Name for form submission. | |
disabled | boolean | Disable the select. Defaults to the enclosing field's disabled. | |
required | boolean | Make selection required. Defaults to the enclosing field's required. | |
allowDeselect | boolean | false | Allow clicking the selected item again to clear it. |
children | Snippet | The Select.* parts. |
Select.Content
The floating panel of a Select, portaled to the body. Render a
Select.Viewport inside it.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element 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. |
sideOffset | number | 4 | Gap in pixels between the trigger and the panel. |
alignOffset | number | 0 | Shift in pixels along the alignment axis. |
portal | PortalTarget | true | Where 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.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element 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>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
value | string | The value this item selects when chosen. | |
label | string | Text shown for the item and matched by typeahead. Falls back to value. | |
disabled | boolean | false | Prevent the item from being selected. |
children | Snippet<[{ 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>| Prop | Type | Default | Description |
|---|---|---|---|
indicator | Snippet | Replaces the trailing chevron. | |
state | FieldState | Contextual 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.