# Combobox
Search a list of options and choose one or several values.
Use a Combobox when people need to find a choice by typing. Start with an input and a list, then add chips, server results, or the option to create something new as you need them.
```svelte title="demo.svelte"
Framework
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Type “sv” to find SvelteKit. Press Down Arrow to highlight it, then Enter to choose it.
## Installation
```bash
npm install @ui-sdk/svelte @ui-sdk/core
```
## Composition
Use the following composition to build a `Combobox`:
```text
Combobox
├── ComboboxLabel
├── ComboboxInput
└── ComboboxContent
└── ComboboxList
├── ComboboxItem
└── ComboboxItem
```
Name the input, give each option a unique value, and put the options in a list inside the popup. The label names the input; choosing an option puts its label in the input.
## Usage
Import the parts and put them together:
```svelte
FruitAppleBanana
```
## Autocomplete vs Combobox
Both filter a list as you type. They differ in what the value is.
- **Combobox**: the value is an option from the list, or several with `multiple`. The text is only a query; closing without choosing restores the selected label, and a form submits the value, not the text. Use it for a country, an assignee or a set of labels.
- **[Autocomplete](/docs/svelte/components/autocomplete)**: the value is the text. Suggestions help fill it in, and anything typed is valid. Use it for a search box, an address or a free-form field.
`allowCustomValue` lets a combobox accept text that matches no option, like a datalist. Reach for it when choosing from the list is the main path; use an autocomplete when free text is.
## Build Your Own
`@ui-sdk/svelte/combobox` comes with a ready-made Combobox. If you'd like to build your own, with your own names, start from the `combobox` primitive in `@ui-sdk/core`:
```ts title="country-picker.ts"
import { combobox } from "@ui-sdk/core/combobox"
import { createParts } from "@ui-sdk/svelte/primitive"
const {
Root: CountryPicker,
Label: CountryLabel,
Input: CountryInput,
Content: CountryPopup,
List: CountryList,
Item: CountryOption,
Empty: CountryEmpty,
} = createParts(combobox, {
label: "label",
input: "input",
content: "div",
list: "div",
item: "div",
empty: "div",
})
export {
CountryEmpty,
CountryInput,
CountryLabel,
CountryList,
CountryOption,
CountryPicker,
CountryPopup,
}
```
```svelte
CountryNo countries found.FranceJapan
```
Each part keeps the behavior, state and data attributes of its ready-made counterpart: typing filters the options, arrow keys move the highlight and the popup opens in the top layer. See [Rendering](/docs/svelte/rendering) and [Custom Parts](/docs/svelte/custom-parts) for more.
## Disabled
A disabled combobox cannot be focused or changed and submits nothing. A read-only one remains focusable and submits its value, but does not open or accept changes. Keyboard navigation skips a disabled option, and it cannot be chosen.
```svelte title="disabled.svelte"
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
{/each}
```
Billing country is disabled and Shipping from is read-only. Open Shipping to: arrow keys skip Denmark, which can't be chosen.
## Clear and Trigger
`ComboboxClear` clears both the selection and the query, then keeps focus in the input. It appears while either has a value. When someone deletes all the text, a single selection clears right away instead of when the list closes. Escape brings the selection back while the list is still open; closing it any other way leaves it cleared.
```svelte title="clear.svelte"
log(`${next ? frameworkLabel(next) : "Cleared"} (${details.reason})`)}
itemToLabel={frameworkLabel}
>
Framework
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Choose a framework, then press the clear button. The selection and text clear, focus stays in the input, and the console logs each change.
## Auto Highlight
Add `autoHighlight` to highlight the first match while typing, so Enter can choose it immediately. With `autoHighlight="always"`, opening the list also highlights the selected item, or the first, so the arrow keys move from there. A highlight it placed follows the list as items arrive, and one the user moved stays while its item is there.
```svelte title="auto-highlight.svelte"
Country
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
```
Type “sw” and press Enter. The first matching country is already highlighted.
## Highlight Matches
`ComboboxItemText` marks the matching text. Matching ignores case and accents using the current locale, while the label keeps its original spelling. Its state also exposes segments if you want to render the marks yourself.
```svelte title="highlight.svelte"
Country
No countries found.
{#each countries as country (country.value)}
{#snippet render({ props, state })}
{#each state.segments as segment, index (index)}
{#if segment.match}
{segment.text}
{:else}
{segment.text}
{/if}
{/each}
{/snippet}
{/each}
```
Type “an”. Matching letters are marked while each country keeps its original spelling.
## Filter and Keywords
`filter` accepts `"contains"` (the default), `"startsWith"`, a function of the item and query, or `false` for results already filtered by a server. A function can return a score instead of `true` or `false`, and items you pass as `items` then sort by it, best first. `fuzzyScore` from `@ui-sdk/core/text-match` scores an exact match above a prefix, and a prefix above a match inside the label.
Use `keywords` for text that should match without appearing in the label, such as a username or a country’s local name.
```svelte title="filter.svelte"
Country
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
```
Type “an” and switch Filter between Contains and Starts with. Choose Fuzzy and type “swd” for Sweden, or type “deutschland” to find Germany through a keyword.
## Groups
Use `ComboboxGroup` and `ComboboxGroupLabel` to name groups. Filtering hides empty groups and separators as their items disappear.
```svelte title="groups.svelte"
Timezone
No cities found.
{#each timezones as group, index (group.label)}
{#if index > 0}{/if}
{group.label}
{#each group.items as item (item.value)}
{item.label}
{/each}
{/each}
```
Type “chic”. Chicago remains in Americas; groups with no matches disappear.
## Icons
`ComboboxItemIcon` keeps decorative icons out of accessible names, filtering, and match marks. `ComboboxValueIcon` projects the selected item’s icon next to the input; it takes no children and is only for a single selection.
Wrap the input and icon together, then use that wrapper as the popup’s `anchor`. Add `mirror` for directional icons. An icon-only option still needs an `aria-label`.
```svelte title="icons.svelte"
Status
No statuses found.
```
Choose Done. Its icon appears next to the input as well as in the list.
## Custom Items
Show useful context beside a label, such as a username or role. Set `label` explicitly so filtering and the input use the intended text, and put extra search terms in `keywords`.
```svelte title="custom-items.svelte"
Owner
No people found.
{#each users as user (user.id)}
{user.name.slice(0, 1)}
{user.name}@{user.username}
{user.role}
{/each}
```
Search for a person’s name or username. Choose a result to put that person’s name in the input.
## Items as Data
Pass `items` when the combobox needs the whole collection, such as recent items, server results, or virtualization. It can render bare parts for you, or you can render the parts yourself from the list's `state.items`. Each item's `label` supplies the text for filtering and the input; `keywords` and `disabled` work the same as with items you render yourself. [Lists and Menus](/docs/svelte/lists-and-menus) covers the `ListData` format.
```svelte
```
Items can change while the list is open. Selection and highlight stay on their items; removing the highlighted item clears the highlight.
## Recent Items
`emptyItems` supplies suggestions while the query is empty. Pair it with `items` for the full searchable collection. Render the list from `state.items` so it follows the active collection.
```svelte title="recent.svelte"
Country
No countries found.
{#snippet children(state)}
{#snippet countryItem(country: { value: string; label: string })}
{/snippet}
{#each state.items as ((typeof countries)[number] | (typeof recentCountries)[number])[] as entry ("items" in entry ? entry.label : entry.value)}
{#if "items" in entry}
{entry.label}
{#each entry.items as country (country.value)}
{@render countryItem(country)}
{/each}
{:else}
{@render countryItem(entry)}
{/if}
{/each}
{/snippet}
```
Open the empty input to see Recent. Start typing to search all countries; clear the text to return to Recent.
## Object Values
Use `itemToValue` for an object’s string identity and form value, `itemToLabel` for its displayed text, and `isItemEqualToValue` when two different objects can represent the same option.
```svelte
String(person.id)}
itemToLabel={(person) => person.name}
isItemEqualToValue={(person, value) => person.id === value.id}
/>
```
## Multiple
Add `multiple` to make the value an array. Choosing an option toggles it, keeps the list open, and clears the query. Put `ComboboxValue` and the input inside `ComboboxChips`, then render each value as a chip with a removal button.
Backspace in an empty input removes the last chip in one press. Unlike [Token Input](/docs/svelte/components/token-input#deleting-tokens), there is no `tokenDeletion` option to select it first. Arrow keys move between chips. Supply `itemToLabel` when starting with values whose labels are not yet known from rendered items.
Add `keepQuery` to choose several matches without retyping the query.
```svelte title="multiple.svelte"
Frameworks
{#snippet children(state)}
{#each state.value as string[] as value, index (value)}
{state.labels[index]}
{/each}
{/snippet}
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Choose several frameworks. Remove one with its chip button, or press Backspace in the empty input to remove the last chip.
## Select All
`ComboboxSelectAll` toggles every matching, enabled option. Inside a group, it affects only that group. It joins keyboard navigation and reports a mixed state while some of its options are selected.
```svelte title="select-all.svelte"
Timezones
{#snippet children(state)}
{#each state.value as string[] as value, index (value)}
{state.labels[index]}
{/each}
{/snippet}
No timezones found.
Select all
{#each timezones as group (group.label)}
{group.label}
{#snippet children(state)}
{state.checked
? `Clear ${group.label}`
: `Select all in ${group.label}`}
{/snippet}
{#each group.items as zone (zone.value)}
{zone.label}
{/each}
{/each}
```
Open the list and choose a group’s select-all option. Type to narrow the matches, then use the main select-all option on those results.
## Chips That Collapse
Add `ComboboxChipsOverflow` to keep chips on one line. It measures which chips fit, hides the rest, and exposes their count and labels. Separately, `ComboboxValue` can use `max` to show a short text summary of the selection.
```svelte title="chips-overflow.svelte"
Countries
{#snippet children(state)}
{#each state.value as string[] as value, index (value)}
{state.labels[index]}
{/each}
{/snippet}
{#snippet render({ props, state })}
+{state.count}
{/snippet}
`${count} more`}
/>
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
```
Add or remove countries. Chips that no longer fit are replaced by an overflow count; the summary below lists the first two.
## Max Selected
`maxSelected` limits a multiple selection. Once the limit is reached, other options become disabled; their `maxReached` state explains why.
```svelte title="max-selected.svelte"
Labels (up to 3)
{#snippet children(state)}
{#each state.value as string[] as label (label)}
{label}
{/each}
{/snippet}
{#each labels as label (label)}
{#snippet children(state)}
{label}
{#if state.maxReached}
Limit reached
{/if}
{/snippet}
{/each}
```
Choose a third label. Other unselected labels become unavailable until you remove one.
## Create Option
`ComboboxCreate` offers the query when no label matches it exactly and it meets `minLength`. Use `onCreate` to save it; return a promise for asynchronous work. Creation does not change the selection itself: add the new item and select it after saving.
While saving, the option reports `data-pending`, `aria-busy` and `aria-disabled`. A rejected promise is available through its error state.
```svelte title="create.svelte"
Labels
{#snippet children({ value: selected })}
{#each selected as string[] as label (label)}
{label}
{/each}
{/snippet}
{#each labels as label (label)}
{label}
{/each}
{#snippet children(state)}
{#if state.pending}
Creating “{state.query}”…
{:else}
Create “{state.query}”
{#if state.error}{(state.error as Error).message}{/if}
{/if}
{/snippet}
```
Type a new label and choose Create. It becomes a selected chip after saving; a label longer than 20 characters shows an error.
## Custom Value
Use `allowCustomValue` when suggestions are optional, like a datalist. Unmatched text becomes the value on Enter with nothing highlighted, or when the list closes. This does not create a new item in the collection.
```svelte title="custom-value.svelte"
log(`${next ? `“${next}”` : "No title"} (${details.reason})`)}
>
Job title
{#snippet children(state)}
{#if state.empty}Press Enter to use “{state.query}”.{/if}
{/snippet}
{#each titles as title (title)}
{title}
{/each}
```
Type a job title that isn't suggested, then press Enter without a highlighted option or leave the field. The text becomes the value, and the console logs it.
## Input in the Popup
The input can live inside the popup, opened by a button showing the current value. The button then stays in the tab order. Anchor the content to it, clear the query when opening, and return focus to it after closing, as this example does.
```svelte title="popup.svelte"
open && (query = "")}
onOpenChangeComplete={(open: boolean) => !open && button?.focus()}
>
{#snippet render({ props })}
{/snippet}
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
```
Press Country to open the search field inside the popup. Choose a country; closing the popup returns focus to the button.
## Async Search
Use [useAsyncOptions](/docs/svelte/utilities/async-options) to debounce a search and discard stale results. Pass its `items` and `status` to the combobox, set `filter` to `false`, and send query changes to the loader.
`ComboboxStatus` and `ComboboxEmpty` provide loading, error, and empty messages. Without a custom status, the combobox announces the result count once typing pauses.
```svelte title="async.svelte"
movies.setQuery(query)}
>
Movie
{#snippet children(state)}
{state.status === "error"
? "Couldn't load movies."
: state.loading
? "Searching…"
: `${state.count} ${state.count === 1 ? "movie" : "movies"}`}
{/snippet}
{#snippet children(state)}
{#if state.empty && !state.loading}No movies match “{state.query}”.{/if}
{/snippet}
{#snippet children(state)}
{#each state.items as { value: string; label: string; disabled?: boolean }[] as item (item.value)}
{item.label}
{/each}
{/snippet}
```
Replace “the” with another movie title. The status shows the pending search, then the latest results.
## Load More
`onLoadMore` runs when scrolling or highlighting reaches the last option, once per page and not while a page loads. Connect it to the async loader’s `loadMore()`; return `{ items, hasMore }` from each page.
```svelte title="infinite.svelte"
movies.setQuery(query)}
onLoadMore={movies.loadMore}
>
Movie
{#snippet children(state)}
{#if state.empty && !state.loading}No movies found.{/if}
{/snippet}
{#snippet children(state)}
{#each state.items as { value: string; label: string; disabled?: boolean }[] as item (item.value)}
{item.label}
{/each}
{/snippet}
{#snippet children(state)}
{state.loading
? "Loading more…"
: movies.state.hasMore
? `${state.count} loaded`
: `All ${state.count}`}
{/snippet}
```
Open the movies and scroll or arrow to the last result. Another page loads while the existing results stay available.
## Virtualized
Supply `items` so filtering and keyboard navigation know about every option, even when only a few rows render. The list’s `state.items` contains matches, `onHighlight` reports the row to reveal, and each rendered item’s `index` gives its position in the full list to screen readers.
This example windows 10,000 items. Keep the actual row height aligned with your virtualizer’s measurement, and use the scroller’s visible height when revealing a row.
```svelte title="virtualized.svelte"
{#each visible(state.items as { value: string; label: string }[]) as { item, index } (item.value)}
{item.label}
{/each}
{/snippet}
```
Search 10,000 items or move through them with the arrow keys. Only the nearby rows render.
## Controlled
The selection, text, and popup have separate values:
| Value | Change notification | Meaning |
| ------- | ------------------- | ---------------------------------------------- |
| `value` | `onValueChange` | One value or `null`; an array with `multiple`. |
| `query` | `onQueryChange` | The input’s text. |
| `open` | `onOpenChange` | Whether the popup is open. |
Control only the values you need; `value`, `query` and `open` can also be bound with `bind:`. Change callbacks include a reason and `details.cancel()` to reject the request. Choosing an item writes its label into the input, and a canceled choice keeps the current one. Closing without choosing restores the value’s label unless custom values are allowed. [State and Events](/docs/svelte/state-and-events) covers the binding pattern.
Focus leaving the input closes the popup with the reason `focus-out`, even when code moves it, like a notice that takes focus. To keep the popup open, cancel that close in `onOpenChange`.
```svelte title="controlled.svelte"
No countries found.
{#each countries as country (country.value)}
{country.label}
{/each}
```
Type, choose, or use the buttons. The console logs each value, query and open change with its reason.
## Controller
Pass a controller from `createComboboxController()`. It can read or set the value and query, open or close the list, and focus the input. `open()` resolves when the list closes with its reason and source, including `unmount`; pass an abort signal to close it on cancellation. [Controllers](/docs/svelte/controllers) covers lifetime and setup.
```svelte title="controller.svelte"
Country
No countries found.
{#each countries as item (item.value)}
{item.label}
{/each}
```
Use the buttons to drive the combobox from outside. Open and Wait logs how the list closed and what was chosen.
## Positioning
`side` and `align` place the popup around the input or chips. `anchor` can use a different element, and `ComboboxArrow` follows the side chosen after collision handling. [Popups](/docs/svelte/popups#place-the-content) covers offsets and available space.
The page stays usable by default. `modal="pointer"` makes an outside press only dismiss the list; `modal` also locks scrolling and makes the rest of the page inert. The popup uses the top layer and renders in place; use `container` when its DOM belongs elsewhere, such as a shadow root.
```svelte title="positioning.svelte"
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Pick a side and an alignment, then open the list. Check Anchor to the Box to place it against the box instead of the input.
## Animation
The content has `data-starting-style` while it opens and `data-ending-style` while it closes. Transition from those states, and the popup stays mounted until the exit finishes. `onOpenChangeComplete` runs after opening or closing finishes, and `keepMounted` on an item indicator keeps it in the page for a selection animation.
```css
[data-slot="combobox-content"] {
transition:
opacity 0.15s,
translate 0.2s cubic-bezier(0.22, 1, 0.36, 1);
&:is([data-starting-style], [data-ending-style]) {
opacity: 0;
translate: 0 -6px;
}
}
```
```svelte title="animation.svelte"
log(open ? "Finished opening" : "Finished closing")}
>
Framework
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Open and close the list. The console logs when each animation finishes.
## Presentation
Use `presentation="sheet"` for a sheet, or `"auto"` to choose a sheet on small touch screens each time the list opens. The input moves into the sheet’s header; there is still one input and one query.
A touch opening leaves the keyboard closed. Tapping the header input opens the keyboard and grows the sheet; closing the keyboard keeps the query. Choosing an item closes the sheet unless `multiple` is set. Swiping down closes it with the reason `swipe`.
Keep the options inside `ComboboxList` so the header stays outside the listbox. Give sheet content a height, style it with `data-presentation`, and leave its `translate` for the sheet behavior. `--sheet-backdrop` controls the backdrop. The sheet is modal unless you set `modal` to false; mouse and keyboard openings keep input focus as it moves.
```svelte title="presentation.svelte"
Framework
No frameworks found.
{#each frameworks as framework (framework.value)}
{framework.label}
{/each}
```
Open the field to see a sheet. On touch, tap the search field in its header to bring up the keyboard, or swipe down to close it.
## Forms
A combobox submits the selected value under `name`, rather than the query text. Multiple values submit as separate entries. `required` prevents empty submissions, reset restores the default selection and its label, and `form` joins a form from elsewhere on the page.
The server HTML includes the hidden inputs for the selection, so their values can submit before hydration. [Forms](/docs/svelte/forms) covers the shared integration.
In a [Field](/docs/svelte/components/field), the field supplies the input's accessible name, description and error. Submitting a required field without a selection sets `aria-invalid` and `data-invalid`.
```svelte title="form.svelte"
```
Submit without a country to see the inline error. Choose one and submit; the console logs the values, and Reset restores the defaults.
## Custom Rendering
Every part takes a `render` snippet, which receives the props to spread and the part's state, and the `children` snippet receives the state too. Each part's state is listed [below](#state).
```svelte title="custom-rendering.svelte"
No one by that name.
{#each users as user (user.id)}
{#snippet children(state)}
{user.name.slice(0, 1)}
{user.name}
@{user.username}
{#if state.selected}
{:else if state.highlighted}
Enter
{/if}
{/snippet}
{/each}
```
Open the list and move through it. The chevron flips while it's open, the highlighted person shows Enter, and the chosen one shows a check.
## Styling
Each part has a `data-slot`, such as `combobox-content`, and shows its state through the attributes listed under [Data Attributes](#data-attributes).
Use `data-highlighted` for the active option and `data-selected` for chosen values. Because the keyboard highlight usually moves without focus leaving the input, use the content's `data-modality="keyboard"` to style it. Real focus can move into the list for touch screen readers or into the sheet.
`--anchor-width` follows the input or chips. `--available-height` doesn't inherit: when a nested scroller needs it, copy it to a custom property on the content, such as `--list-height: var(--available-height)`, then use that property on the scroller.
### ComboboxContent
- `--anchor-width`: Width of the anchor, usually the trigger. Use it to match widths.
- `--anchor-height`: Height of the anchor.
- `--available-width`: Space beside the popup, up to the viewport edge. Not inherited either.
- `--available-height`: Space between the anchor and the viewport edge. Use it for max-height. Not inherited, so a child that needs it copies it on the popup, like `[--list-height:var(--available-height)]`, and reads `max-h-(--list-height)`. The first popup registers both names for the whole page with `CSS.registerProperty`, so they don't inherit anywhere. A page that needs them to inherit calls it first, with `inherits: true`. An `@property` rule can't, since a registration in script wins.
- `--transform-origin`: The point on the anchor the popup opens from. Use it to scale from the right place.
- `--arrow-offset`: Where the anchor's center falls along the popup's edge, kept `arrowPadding` from the corners. Position a ::before arrow with it.
- `--drawer-progress`: While it presents as a sheet: how far open the sheet is, from 0 closed to 1 at its largest snap point. Never past 1.
- `--drawer-dim`: While it presents as a sheet: how dim the page behind is, from 0 to 1. The backdrop's opacity follows it.
- `--drawer-expand`: While it presents as a sheet: 0 at the second-largest snap point and below, 1 at the largest. With one snap point, the whole travel.
- `--drawer-stack`: While it presents as a sheet: how many sheets opened from inside this one are open above it, rising smoothly as each one opens. Push it back with it.
- `--sheet-backdrop`: Set it yourself: the color the page dims to while it presents as a sheet. Black at 0.2 by default.
### Viewport
- `--keyboard-inset`: While it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one.
- `--visual-viewport-width`: While it presents as a sheet: the width of the part of the page you can see.
- `--visual-viewport-height`: While it presents as a sheet: the height of the part of the page you can see, above the keyboard.
- `--visual-viewport-top`: While it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up.
## Data Attributes
### ComboboxLabel
`[data-slot="combobox-label"]`
- `data-disabled`: Present when the combobox is disabled, by its own prop, a field or a `