Combobox

An input with an associated popup containing a list of options. Commonly used for autocomplete functionality and command palettes.

View code

Choose your favorite manga:

Features

Full keyboard navigation
Declarative API
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
- Label: The label for the input
- Arrow: An optional arrow element which points to the menu's input

Examples

Multiple

We expose a multiple prop to allow for multiple selections.

View code

Choose your favorite manga:

Debounce

Sometimes you may want to debounce user input in the input element. This pattern can be useful to prevent over-requesting data from a server, for example.

View code

Choose your favorite manga:

API Reference

createCombobox

The builder function used to create the combobox component.

Props

Prop	Default	Type / Description
`defaultSelected`	-	`ComboboxOption<T>` The initial selected item.
`selected`	-	`Writable<ComboboxOption<T>>` A writable store that can be used to get or update the selected item. See Bring Your Own Store
`onSelectedChange`	-	`ChangeFn<ComboboxOption<T>>` A callback that is called when the selected item changes. See Change Functions
`multiple`	`false`	`boolean` Whether or not the combobox is a multiple combobox.
`defaultOpen`	`false`	`boolean` Whether the combobox is open by default or not.
`open`	-	`Writable<boolean>` A writable store that controls whether or not the combobox is open. See Bring Your Own Store
`onOpenChange`	-	`ChangeFn<boolean>` A callback called when the value of the `open` store should be changed. See Change Functions
`scrollAlignment`	`'nearest'`	`'nearest' \| 'center'` The alignment of the highlighted item when scrolling.
`loop`	`false`	`boolean` Whether or not the focus should loop back to the first item when the last item is reached.
`closeOnOutsideClick`	`true`	`boolean` Whether or not to close the combobox when the user clicks outside of it.
`closeOnEscape`	`true`	`boolean` Whether or not to close the combobox when the escape key is pressed.
`preventScroll`	`true`	`boolean` Whether or not to prevent scrolling of the document when the combobox is open.
`portal`	`body`	`string \| HTMLElement` The element or selector to render the combobox into. Nested floating elements are automatically rendered into their parent if not specified.
`positioning`	`placement: 'bottom'`	A configuration object which determines how the floating element is positioned relative to the trigger.
`forceVisible`	`false`	`boolean` Whether or not to force the combobox to always be visible. This is useful for custom transitions and animations using conditional blocks.
`highlightOnHover`	`true`	`boolean` When true, hovering an option will update the `highlightedItem` store, and when the cursor leaves an option the store will be set to `null`
`ids`	-	`Record<'trigger' \| 'content', string>` Override the internally generated ids for the elements.
`ids`	-	`Record<'trigger' \| 'menu' \| 'label', string>` Override the internally generated ids for the elements.

Elements

Element	Description
`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.
`label`	The builder store used to create the label for the combobox.

States

State	Description
`open`	A writable store with the open state of the combobox menu.
`inputValue`	A readable store with the value of the input.
`touchedInput`	A writable store with the touched state of the input. When the menu closes, the state is reset to `false`. Whenever a key is pressed into the input, the state is set to `true`.
`selected`	A writable store whose value is the selected item.
`highlighted`	A writable store whose value is the highlighted item.

Helpers

Helper	Description
`isSelected`	A derived store that returns a function that returns whether or not the item is selected.
`isHighlighted`	A derived store that returns a function that returns whether or not the item is highlighted.

Options

Option	Description
`scrollAlignment`	The alignment of the highlighted item when scrolling.
`loop`	Whether or not the focus should loop back to the first item when the last item is reached.
`closeOnOutsideClick`	Whether or not to close the combobox when the user clicks outside of it.
`closeOnEscape`	Whether or not to close the combobox when the escape key is pressed.
`preventScroll`	Whether or not to prevent scrolling of the document when the combobox is open.
`portal`	The element or selector to render the combobox into. Nested floating elements are automatically rendered into their parent if not specified.
`positioning`	A configuration object which determines how the floating element is positioned relative to the trigger.
`forceVisible`	Whether or not to force the combobox to always be visible. This is useful for custom transitions and animations using conditional blocks.
`highlightOnHover`	When true, hovering an option will update the `highlightedItem` store, and when the cursor leaves an option the store will be set to `null`

IDs

Option	Description
`trigger`	The writable store that represents the id of the `trigger` element.
`menu`	The writable store that represents the id of the `menu` element.
`label`	The writable store that represents the id of the `label` element.

The combobox menu element

Data Attributes

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

Custom Events

Event	Value
`m-pointerleave`	`(e: ) => void`

input

The element that opens, closes, filters the list, and displays the selected value from the list.

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.

Custom Events

Event	Value
`m-click`	`(e: ) => void`
`m-keydown`	`(e: ) => void`
`m-input`	`(e: ) => void`

item

The menu item element

Props

Prop	Default	Type / Description
`value` *	-	`T` The value of the item.
`label`	-	`string` The label of the item. When not present, the text content will be used.
`disabled`	`false`	`boolean` Whether or not the `item` is disabled.

Data Attributes

Data Attribute	Value
`[data-disabled]`	Present when the `item` is disabled.
`[data-selected]`	Present when the `item` is selected.
`[data-highlighted]`	Present when the element is highlighted.
`[data-melt-combobox-item]`	Present on all item elements.

Custom Events

Event	Value
`m-pointermove`	`(e: ) => void`
`m-click`	`(e: ) => void`

label

The label element for the combobox

Data Attributes

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

arrow

An optional arrow element which points to the menu's trigger.

Data Attributes

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

hidden-input

The hidden input element. Used for form submission.

Data Attributes

Data Attribute	Value
`[data-melt-combobox-hidden-input]`	Present on all hidden-input 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