Combobox

Installation

pnpm dlx @mielui/svelte add combobox

npx @mielui/svelte add combobox

yarn dlx @mielui/svelte add combobox

bunx @mielui/svelte add combobox

Usage

Bind value to the selected option. Single selection is the default. Clicking an option or pressing Enter updates value and calls onValueChange. Keyboard navigation skips disabled options. Changing an item label updates the selected label without replacing an active search.

Set name on Trigger to submit the selected value. Search text and labels are not submitted. Trigger renders an input by default, or a button with searchPlacement="menu". Its bind:element matches that element type.

An item callback runs when that option changes the selection. Selecting the current option again in single mode closes the menu without reporting a value change. Call preventDefault() in Trigger's onclick to cancel click activation. Input appearance can still open on focus or typing. Trigger's disabled prop disables both editing and its clear action.

Set type="multiple" on Root and bind a string array to value to choose several options. Selecting an item toggles it, clears the search, and keeps the menu open. The trigger lists selected labels; Escape or an outside click closes the menu. With name on Trigger, each selected value submits under that name.

<script lang="ts">
    import * as Combobox from '@mielui/svelte/components/combobox';

    let framework = $state('sveltekit');
</script>

<Combobox.Root bind:value={framework}>
    <Combobox.Trigger placeholder="Select a framework" />
    <Combobox.Content>
        <Combobox.Results>
            <Combobox.Item value="nextjs" label="Next.js" />
            <Combobox.Item value="sveltekit" label="SvelteKit" />
        </Combobox.Results>
    </Combobox.Content>
</Combobox.Root>

Glass surface

Set surface="glass" on Content for a translucent panel with blur, or surface="solid" for an opaque one. Without surface, the panel follows the theme. Glass falls back to an opaque panel when backdrop filtering is unavailable or reduced transparency is on.

Custom item content

Item renders its label by default. Pass children to show an icon or a second line instead. The label is still required: search matches against it and the trigger shows it once the item is selected.

<Combobox.Item value="fr" label="France">
  <span>France</span>
  <span class="text-foreground-muted">Europe</span>
</Combobox.Item>

Labels

Built-in text is English. Pass a ComboboxLabels object to labels on Root to translate or reword the menu search placeholder and name, the clear button, the option list name and the empty message. Every key is optional, and an omitted key keeps its English default. The trigger placeholder is a prop on Trigger.

<script lang="ts">
    import * as Combobox from '@mielui/svelte/components/combobox';
    import type { ComboboxLabels } from '@mielui/svelte/components/combobox';

    const labels: ComboboxLabels = {
        searchPlaceholder: 'Rechercher…',
        search: 'Rechercher un pays',
        clear: 'Effacer',
        options: 'Pays',
        empty: 'Aucun résultat'
    };
</script>

<Combobox.Root {labels}>
    <Combobox.Trigger placeholder="Choisir un pays" searchPlacement="menu" />
    <Combobox.Content>
        <Combobox.Results>
            <Combobox.Item value="fr" label="France" />
            <Combobox.Item value="be" label="Belgique" />
        </Combobox.Results>
    </Combobox.Content>
</Combobox.Root>

Matching typed text

The combobox filters with fuzzy matching, so a small typo still finds the option. threshold on Trigger sets how forgiving it is, from 0 for an exact match to 1 for nearly anything. The default is 0.28. Lower it for lists of codes or ids where a near miss is a wrong answer.

Opening and placement

placement on Root picks the side and alignment of the list, such as top-start. It defaults to bottom and flips when there is no room. onOpenChange runs when the person opens or closes the list, and onopen on Trigger runs just before it opens, which is the place to fetch options.

hoverable opens the list when the pointer rests on the trigger, with delay and closeDelay in milliseconds. inert is on by default and makes the rest of the page inert while a click-opened list is showing.

Panel and items

Content shares its panel with Popover. allowClickOutside={false} keeps the list open on an outside press, and dismissLayer={false} removes the invisible layer that catches the first outside press, which the input-style trigger relies on to stay typeable. lockScroll decides whether page scrolling is held while it is open; Tab is never trapped, so it moves on from the list. portal={false} renders the list in place, refElement anchors it to another element, and role and tabindex set the panel's ARIA role and tab index. surfaceClass styles the inner surface while class styles the frame.

Item is built on Button and always uses the menu row style, so Button's variant, size, and unstyled do not apply. A row is always a button and does not take href. status or loading show progress on a row, with labels setting the text for each state, and onkeydown runs before the list handles the key. Trigger takes Button's size, style, and unstyled.