Skip to content

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 bindable query for the text typed since the list opened.
  • items is the single source of truth for the options. The input shows the selected label, and Combobox.Items renders the ones the filter keeps.
  • Combobox.Input takes state from an enclosing Field, or directly. Both it and Combobox.Trigger sit in an Input.Group.
  • The list floats in a portal, positioned to the input.
  • To pick from a fixed list without typing, use Select.

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>

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
TwoWay.svelte
<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>

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 { 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>

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
Grouped.svelte
<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>

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
CustomFilter.svelte
<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>

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
Remote.svelte
<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>

Placeholder, with a disabled item

Error

Disabled

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.

With focus on the input:

KeyAction
ArrowDown / ArrowUpOpens the list and highlights an item.
Printable charactersOpens the list and filters it to matches.

With the list open:

KeyAction
ArrowDown / ArrowUpHighlights the next or previous item.
EnterSelects the highlighted item and closes.
EscapeCloses without changing the value.
TabCloses and moves focus on.
PropTypeDefaultDescription
itemsSelectOption[]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:valuestringThe selected value. Two-way bindable.
bind:querystringThe text typed since the list last opened, '' while it is closed. Two-way bindable.
filterComboboxFiltermatchesLabelDecides whether an option stays in the list for the typed text. The default keeps options whose label contains the trimmed text, ignoring case.
namestringName for form submission.
disabledbooleanDisable the combobox. Defaults to the enclosing field's disabled.
requiredbooleanMake selection required. Defaults to the enclosing field's required.
allowDeselectbooleanfalseAllow picking the selected item again to clear it.
childrenSnippetThe 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.

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 input's frame the panel opens on.
align'start' | 'center' | 'end''start'Alignment of the panel along the frame's edge.
sideOffsetnumber4Gap in pixels between the frame 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.

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.

PropTypeDefaultDescription
idstringElement 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>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
stateFieldStateContextual 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>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
valuestringThe value this item selects when chosen.
labelstringText shown for the item and in the input once it is selected. 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.

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>
PropTypeDefaultDescription
idstringElement id. null is not accepted.
indicatorSnippetReplaces 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.