Combobox

A filterable list of items that supports selection.

View code

Choose your favorite book:

Features

Full keyboard navigation
Updatable data source
Can be controlled or uncontrolled
Custom positioning

Anatomy

Input: The input that opens, closes, filters the list, and displays the selected value from the list
Menu: The popover menu
Item: The individual list item

API Reference

createCombobox

Props

Prop	Default	Type / Description
`filterFunction`	-	`(item: T, inputValue: string)` A function that returns `true` if the item should be included in the filtered list.
`items`	-	`T[]` The list of items to display in the combobox list.
`itemToString`	-	`(item: T)` A function that returns a string representation of the item.
`loop`	`false`	`boolean` Whether or not the combobox should loop through the list when the end or beginning is reached.
`scrollAlignment`	`'nearest'`	`'nearest' \| 'center'` The alignment of the highlighted item when scrolling.

Returned Props

Returned Prop	Type	Description
`filteredItems`	`Readable<T[]>`	A derived store that returns the filtered list of items.
`updateItems`	`UpdaterFunction: (items: T[]) => T[]`	A function that updates the list of items.
`inputValue`	`Writable<string>`	A writable store that controls the value of the input.
`isSelected`	`Readable<(item: T) => boolean>`	A derived store that returns a function that returns whether or not the item is selected.
`selectedItem`	`Writable<T>`	A writable store that controls the selected item.
`options`	`Writable<CreateComboboxProps>`	A writable store with the options used to create the combobox.
`open`	`Writable<boolean>`	A writable store that controls whether or not the combobox is open.
`menu`	-	The builder store used to create the collapsible menu.
`input`	-	The builder store used to create the collapsible input.
`item`	-	The builder store used to create the menu item.

Data Attributes

Data Attribute	Value
`[data-melt-combobox-menu]`	Present on all menu elements.

input

Data Attributes

Data Attribute	Value
`[data-state]`	`'open' \| 'closed'`
`[data-disabled]`	Present when the `select` is disabled.
`[data-melt-combobox-input]`	Present on all input elements.

item

Props

Prop	Default	Type / Description
`label`	-	`string` The label of the `item`.
`value`	-	`unknown` The value of the `item`.
`disabled`	`false`	`boolean` Whether or not the `item` is disabled.

Data Attributes

Data Attribute	Value
`[data-melt-combobox-item]`	Present on all item elements.
`[data-disabled]`	Present when the `item` is disabled.
`[data-index]`	The index of the item in the list.
`[data-highlighted]`	Present when the element is highlighted.

arrow

Data Attributes

Data Attribute	Value
`[data-arrow]`	`'true'`
`[data-melt-combobox-arrow]`	Present on all arrow elements.

Accessibility

Adheres to the Autocomplete/Combobox WAI-ARIA design pattern

Key	Behavior
`Enter`	selects the highlighted list item.
`ArrowDown`	Highlights the next list item.
`ArrowUp`	Highlights the previous list item.
`Home`	Highlights the first list item
`End`	Highlights the last list item
`Esc`	When focus is on the `input` and it's closed, removes focus. When the `input` is open, closes the list.

On This Page