MultiSelect
A select that holds several values. Render MultiSelect.Trigger, MultiSelect.Content,
MultiSelect.Viewport, and MultiSelect.Items inside it, the same parts a Select takes.
Picking an item toggles it and keeps the list open. The closed trigger shows the selected labels joined by commas,
and a name submits one hidden input per value. Inside a Field it takes disabled and
required from there.
Built on bits-ui Select with type="multiple".
<Field class="flex flex-col gap-1"> <Label>Toppings</Label> <MultiSelect bind:value items={toppings}> <MultiSelect.Trigger> <MultiSelect.Value placeholder="Pick toppings" /> </MultiSelect.Trigger> <MultiSelect.Content> <MultiSelect.Viewport> <MultiSelect.Items /> </MultiSelect.Viewport> </MultiSelect.Content> </MultiSelect></Field>- The same parts as
Select, underMultiSelect.*. The trigger, the panel, and each item are yours to arrange. valueis astring[], bindable, in the order the values were picked. Picking an item toggles it and the list stays open.- The closed trigger shows the selected labels joined by commas, and a
namesubmits one hidden input per value. itemsis the single source of truth for the options, as onSelect. Typing while the list is closed toggles the matching entry.- Keyboard navigation, typeahead, and the WAI-ARIA listbox pattern, via bits-ui.
Anatomy
Section titled “Anatomy”The parts are the Select parts, so the Select anatomy applies with MultiSelect in place of Select. Content is the floating panel, portaled to the body, Viewport is the scrolling region, and Items renders every entry of items.
<MultiSelect> <MultiSelect.Trigger> <MultiSelect.Value /> </MultiSelect.Trigger> <MultiSelect.Content> <MultiSelect.Viewport> <MultiSelect.Items /> </MultiSelect.Viewport> </MultiSelect.Content></MultiSelect>Two-way binding
Section titled “Two-way binding”bind:value on the root holds an array. Pass the options as items and render them with <MultiSelect.Items />.
value: ["cheese"]
Code
<script lang="ts"> import { Field, Label, MultiSelect } from "@viamrobotics/prime-ui";
const toppings = [ { value: "cheese", label: "Cheese" }, { value: "olives", label: "Olives" }, { value: "peppers", label: "Peppers" }, ];
let picked = $state(["cheese"]);</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Toppings</Label> <MultiSelect bind:value={picked} items={toppings} name="toppings"> <MultiSelect.Trigger> <MultiSelect.Value placeholder="Pick toppings" /> </MultiSelect.Trigger> <MultiSelect.Content> <MultiSelect.Viewport> <MultiSelect.Items /> </MultiSelect.Viewport> </MultiSelect.Content> </MultiSelect> </Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{JSON.stringify(picked)}</code></p></div>Fully controlled
Section titled “Fully controlled”Pass bind:value a getter and a setter. The setter receives the whole next array, so it can cap how many values are held. State & binding explains both modes.
Up to 2. A third pick is refused.
value: ["cheese"]
Code
<script lang="ts"> import { Field, Hint, Label, MultiSelect } from "@viamrobotics/prime-ui";
const MAX_TOPPINGS = 2;
const toppings = [ { value: "cheese", label: "Cheese" }, { value: "olives", label: "Olives" }, { value: "peppers", label: "Peppers" }, { value: "mushrooms", label: "Mushrooms" }, ];
let picked = $state(["cheese"]);</script>
<div class="not-content"> <Field class="flex max-w-xs flex-col gap-1"> <Label>Toppings</Label> <MultiSelect items={toppings} bind:value={ () => picked, (next) => { if (next.length <= MAX_TOPPINGS) picked = next; } } > <MultiSelect.Trigger> <MultiSelect.Value placeholder="Pick toppings" /> </MultiSelect.Trigger> <MultiSelect.Content> <MultiSelect.Viewport> <MultiSelect.Items /> </MultiSelect.Viewport> </MultiSelect.Content> </MultiSelect> <Hint>Up to {MAX_TOPPINGS}. A third pick is refused.</Hint> </Field>
<p class="mt-3 text-sm text-subtle-2">value: <code>{JSON.stringify(picked)}</code></p></div>States
Section titled “States”Placeholder, with a disabled item
Several values
Error
Disabled
Styling
Section titled “Styling”Everything on the Select styling section applies: class lands on each part’s element, MultiSelect.Trigger carries no width of its own, and bits-ui sets the same data attributes. MultiSelect.Item carries data-selected on every selected item at once.
Keyboard
Section titled “Keyboard”The Select keyboard table applies, with two differences while the panel is open:
| Key | Action |
|---|---|
| Enter / Space | Toggles the highlighted item. The panel stays open. |
| Escape | Closes the panel. The values picked so far are kept. |
| 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 entries' labels. Typing while the list is closed toggles the matching
entry without opening it. | |
bind:value | string[] | The selected values, in the order they were picked. Two-way bindable. | |
name | string | Name for form submission. Submits one input per selected value. | |
disabled | boolean | Disable the select. Defaults to the enclosing field's disabled. | |
required | boolean | Require at least one selection. Defaults to the enclosing field's required. | |
children | Snippet | The MultiSelect.* parts. |
The parts are documented on Select.