Combobox
A text input that filters a list of options as the user types and selects one of them. Render
Combobox.Input, Combobox.Trigger, and
Combobox.Content inside it. Inside a
Field it takes disabled and required from there.
Built on bits-ui Combobox.
<Field class="flex flex-col gap-1"> <Label>Region</Label> <Combobox bind:value items={regions}> <Input.Group> <Combobox.Input placeholder="Search regions" /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No matching region</Combobox.Empty> </Combobox.Viewport> </Combobox.Content> </Combobox></Field>- Composed from parts, so the input, the trigger, and the list are yours to arrange.
- One
value, bindable, and a bindablequeryfor the text typed since the list opened. itemsis the single source of truth for the options. The input shows the selected label, andCombobox.Itemsrenders the ones thefilterkeeps.Combobox.Inputtakesstatefrom an enclosingField, or directly. Both it andCombobox.Triggersit in anInput.Group.- The list floats in a portal, positioned to the input.
- To pick from a fixed list without typing, use
Select.
Anatomy
Section titled “Anatomy”Every part is a property on Combobox. Content is the floating list, portaled to the body, and should contain a Viewport. Items renders every match as a Combobox.Item and renders no element of its own. Empty shows only while nothing matches. Group and GroupHeading are optional.
<Combobox items={options}> <Input.Group> <Combobox.Input /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty /> </Combobox.Viewport> </Combobox.Content></Combobox>Two-way binding
Section titled “Two-way binding”bind:value on the root holds the selection, and bind:query holds what the user has typed. query is empty while the list is closed. Put the combobox in a Field with a Label so the label targets the input.
value: motor, query: ""
Code
<script lang="ts"> import { Combobox, Field, Input, Label } from "@viamrobotics/prime-ui";
const resources = [ { value: "camera", label: "Camera" }, { value: "motor", label: "Motor" }, { value: "base", label: "Base" }, { value: "arm", label: "Arm" }, { value: "sensor", label: "Sensor" }, ];
let resource = $state("motor"); let query = $state("");</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Resource type</Label> <Combobox bind:value={resource} bind:query items={resources}> <Input.Group> <Combobox.Input placeholder="Search resource types" /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No matching resource type</Combobox.Empty> </Combobox.Viewport> </Combobox.Content> </Combobox> </Field>
<p class="mt-3 text-sm text-subtle-2"> value: <code>{resource}</code>, query: <code>{JSON.stringify(query)}</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 { Combobox, Field, Hint, Input, Label } 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> <Combobox items={regions} bind:value={ () => region, (next) => { if (next !== "eu-central") region = next; } } > <Input.Group> <Combobox.Input placeholder="Search regions" /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No matching region</Combobox.Empty> </Combobox.Viewport> </Combobox.Content> </Combobox> <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>Groups
Section titled “Groups”Render Combobox.Item by hand to add structure. Wrap related items in Combobox.Group with a Combobox.GroupHeading. items stays on the root for the input’s label, and reading query lets you drop groups with no match.
Code
<script lang="ts"> import { Combobox, Field, Input, Label } from "@viamrobotics/prime-ui";
const groups = [ { heading: "Arms", items: [ { value: "arm-01", label: "Arm 01" }, { value: "arm-02", label: "Arm 02" }, ], }, { heading: "Rovers", items: [ { value: "rover-alpha", label: "Rover Alpha" }, { value: "rover-beta", label: "Rover Beta" }, { value: "rover-gamma", label: "Rover Gamma" }, ], }, { heading: "Fixed installations", items: [ { value: "gantry-east", label: "Gantry East" }, { value: "sorter-line-3", label: "Sorter Line 3" }, ], }, ];
const machines = groups.flatMap((group) => group.items);
let machine = $state(""); let query = $state("");
const visible = $derived( groups .map((group) => ({ ...group, items: group.items.filter((item) => item.label.toLowerCase().includes(query.trim().toLowerCase()) ), })) .filter((group) => group.items.length > 0) );</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Machine</Label> <Combobox bind:value={machine} bind:query items={machines}> <Input.Group> <Combobox.Input placeholder="Search machines" /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> {#each visible as group (group.heading)} <Combobox.Group> <Combobox.GroupHeading>{group.heading}</Combobox.GroupHeading> {#each group.items as item (item.value)} <Combobox.Item value={item.value} label={item.label} /> {/each} </Combobox.Group> {/each} {#if visible.length === 0} <Combobox.Empty>No matching machine</Combobox.Empty> {/if} </Combobox.Viewport> </Combobox.Content> </Combobox> </Field></div>Custom filter
Section titled “Custom filter”The default filter keeps options whose label contains the typed text, ignoring case. Pass your own to change that. This one keeps labels that start with the text.
Code
<script lang="ts"> import { Combobox, Field, Input, Label, type ComboboxFilter } from "@viamrobotics/prime-ui";
const components = [ { value: "left-motor", label: "left-motor" }, { value: "right-motor", label: "right-motor" }, { value: "motor-controller", label: "motor-controller" }, { value: "front-camera", label: "front-camera" }, { value: "camera-mount", label: "camera-mount" }, ];
const startsWith: ComboboxFilter = (option, query) => option.label.toLowerCase().startsWith(query.trim().toLowerCase());
let component = $state("");</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Component</Label> <Combobox bind:value={component} items={components} filter={startsWith}> <Input.Group> <Combobox.Input placeholder="Starts with..." /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No component starts with that</Combobox.Empty> </Combobox.Viewport> </Combobox.Content> </Combobox> </Field></div>Remote options
Section titled “Remote options”For a long or remote list, fetch in the consumer. Read the bound query, load the matches, and pass them as items. Set filter={() => true} so the combobox shows them all instead of filtering again. The lookup here is simulated locally.
Each keystroke runs a simulated lookup, and the list shows whatever it returned.
Code
<script lang="ts"> import { Combobox, Field, Hint, Input, Label } from "@viamrobotics/prime-ui";
const catalog = [ "arm-01", "arm-02", "camera-front", "camera-rear", "gantry-east", "gantry-west", "rover-alpha", "rover-beta", "rover-gamma", "sorter-line-1", "sorter-line-2", "sorter-line-3", ].map((label, index) => ({ value: `m-${String(index + 1).padStart(4, "0")}`, label }));
const fetchMachines = async (text: string) => { await new Promise((resolve) => setTimeout(resolve, 250)); return catalog .filter((machine) => machine.label.includes(text.trim().toLowerCase())); };
let machine = $state(""); let query = $state(""); let results = $state<{ value: string; label: string }[]>([]); let loading = $state(false);
$effect(() => { const text = query; loading = true; let stale = false; fetchMachines(text).then((found) => { if (stale) return; results = found; loading = false; }); return () => { stale = true; }; });</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Machine</Label> <Combobox bind:value={machine} bind:query items={results} filter={() => true}> <Input.Group> <Combobox.Input placeholder="Search machines" /> <Combobox.Trigger /> </Input.Group> <Combobox.Content> <Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No matching machine</Combobox.Empty> </Combobox.Viewport> </Combobox.Content> </Combobox> <p role="status" class="text-sm text-subtle-2">{loading ? "Searching..." : ""}</p> <Hint>Each keystroke runs a simulated lookup, and the list shows whatever it returned.</Hint> </Field></div>States
Section titled “States”Placeholder, with a disabled item
Error
Disabled
Styling
Section titled “Styling”Every part that renders an element takes class on that element. Combobox and Combobox.Items render no element, so they take no class. Focus shows as the same 2px ring every prime control uses. error sets aria-invalid="true" and the error border, and warn sets the warning border, both from the input component class. Combobox.Content wears z-popover. See z layers.
Keyboard
Section titled “Keyboard”With focus on the input:
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Opens the list and highlights an item. |
| Printable characters | Opens the list and filters it to matches. |
With the list open:
| Key | Action |
|---|---|
| ArrowDown / ArrowUp | Highlights the next or previous item. |
| Enter | Selects the highlighted item and closes. |
| Escape | Closes without changing the value. |
| Tab | Closes and moves focus on. |
| Prop | Type | Default | Description |
|---|---|---|---|
items | SelectOption[] | The options. [Combobox.Items](./ComboboxItems.svelte) renders the ones the filter
keeps for the typed text, and the input shows the selected entry's label. | |
bind:value | string | The selected value. Two-way bindable. | |
bind:query | string | The text typed since the list last opened, '' while it is closed. Two-way bindable. | |
filter | ComboboxFilter | matchesLabel | Decides whether an option stays in the list for the typed text. The default keeps options whose label contains the trimmed text, ignoring case. |
name | string | Name for form submission. | |
disabled | boolean | Disable the combobox. Defaults to the enclosing field's disabled. | |
required | boolean | Make selection required. Defaults to the enclosing field's required. | |
allowDeselect | boolean | false | Allow picking the selected item again to clear it. |
children | Snippet | The Combobox.* parts. |
Combobox.Content
The floating panel of a Combobox, portaled to the body. Render a
Combobox.Viewport inside it. It lines up with the
Input.Group around the
Combobox.Input, or with the input itself when it stands alone.
| 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 input's frame the panel opens on. |
align | 'start' | 'center' | 'end' | 'start' | Alignment of the panel along the frame's edge. |
sideOffset | number | 4 | Gap in pixels between the frame 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.
Combobox.Empty
The message a Combobox shows in its list when no option matches the
typed text. The visible text is hidden from assistive technology, and the Combobox announces
the same message itself from a status region outside the list, rendering children a second time
there, so keep the message to text with no ids or controls. It stays empty while any option
matches. Place it in the
Combobox.Viewport after
Combobox.Items.
<Combobox.Viewport> <Combobox.Items /> <Combobox.Empty>No matching region</Combobox.Empty></Combobox.Viewport>Takes extraClasses, children, ...restProps }: Props as its props.
Combobox.Group
Groups related Combobox.Items, optionally labeled by a
Combobox.GroupHeading.
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. |
Plus everything in HTMLAttributes<HTMLDivElement>, spread onto the element.
Combobox.GroupHeading
A non-selectable heading for a Combobox.Group.
Takes extraClasses, children, ...restProps }: Props as its props.
Combobox.Input
The text input of a Combobox. Typing filters the list and opens it, and
the input shows the selected option’s label otherwise. 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.
Put it in an Input.Group beside a
Combobox.Trigger, and the group takes over its frame:
<Input.Group> <Combobox.Input placeholder="Search regions" /> <Combobox.Trigger /></Input.Group>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
state | FieldState | Contextual state. Defaults to the enclosing field's state. |
Plus everything in Omit<HTMLInputAttributes, 'value'>, spread onto the element.
Combobox.Item
A selectable option within a Combobox.Content.
By default it renders its label (or value) plus a check when selected.
Pass a children snippet to render custom content:
<Combobox.Item value="us-east" label="US East"> {#snippet children({ selected })} <span class:font-medium={selected}>US East</span> {/snippet}</Combobox.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 in the input once it is selected. 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.
Combobox.Items
Renders the items of the enclosing Combobox that match the typed text,
as Combobox.Items. Pair it with a
Combobox.Empty for the message when nothing matches.
Takes content }: Props as its props.
Combobox.Trigger
The button that opens and closes the list of a Combobox. Pressing it keeps
focus in the Combobox.Input. Place it beside the input in an
Input.Group.
A chevron is rendered by default. Pass an indicator snippet to replace it:
<script> import { mdiMenuDown } from '@mdi/js';</script>
<Input.Group> <Combobox.Input /> <Combobox.Trigger> {#snippet indicator()} <Icon icon={mdiMenuDown} size="lg" /> {/snippet} </Combobox.Trigger></Input.Group>| Prop | Type | Default | Description |
|---|---|---|---|
id | string | Element id. null is not accepted. | |
indicator | Snippet | Replaces the chevron. |
Plus everything in Omit<HTMLButtonAttributes, 'children'>, spread onto the element.
Combobox.Viewport
The scrollable region inside a Combobox.Content that holds the
items.
Takes extraClasses, children, ...restProps }: Props as its props.