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
- Option: The individual combobox items
- Label: The label for the input
- Arrow: An optional arrow element which points to the menu's input
- Group: Optional group and group label elements which can be used to group options

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:

Group

The group and groupLabel elements can be used to group combobox list items.

View code

Choose your favorite manga:

Shadow DOM

By default, the comboBox uses the document as the root element to query its internal components. By utilizing the rootElement property you can override this behaviour, this is especially useful when running inside the Shadow DOM.

View code

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.
`escapeBehavior`	`'close'`	`'close' \| 'ignore' \| 'defer-otherwise-close' \| 'defer-otherwise-ignore'` Defines how the combobox reacts when the Escape key is pressed. `close`: Closes the combobox immediately. `ignore`: Prevents the combobox from closing and also blocks the parent element from closing in response to the Escape key. `defer-otherwise-close`: Delegates the action to the parent element. If no parent is found, it closes the element. `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
`preventScroll`	`true`	`boolean` Whether or not to prevent scrolling of the document when the combobox is open.
`preventTextSelectionOverflow`	`true`	`boolean` Whether to prevent text selection overflowing the combobox when it is the top layer.
`portal`	`body`	`string \| HTMLElement \| null` The element or selector to render the combobox into. Nested floating elements are automatically rendered into their own portal if not specified. Pass in `null` to disable portalling. Pass in `undefined` to use parent portal.
`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`
`name`	-	`string` The name to be used for the hidden input.
`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.
`group`	The builder store used to create the combobox group.
`groupLabel`	The builder store used to create the combobox group label.
`hiddenInput`	The builder store used to create the combobox hidden input.
`arrow`	The builder store used to create the combobox arrow.

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.
`escapeBehavior`	Defines how the combobox reacts when the Escape key is pressed. `close`: Closes the combobox immediately. `ignore`: Prevents the combobox from closing and also blocks the parent element from closing in response to the Escape key. `defer-otherwise-close`: Delegates the action to the parent element. If no parent is found, it closes the element. `defer-otherwise-ignore`: Delegates the action to the parent element. If no parent is found, nothing is done.
`preventScroll`	Whether or not to prevent scrolling of the document when the combobox is open.
`preventTextSelectionOverflow`	Whether to prevent text selection overflowing the combobox when it is the top layer.
`portal`	The element or selector to render the combobox into. Nested floating elements are automatically rendered into their own portal if not specified. Pass in `null` to disable portalling. Pass in `undefined` to use parent portal.
`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`
`name`	The name to be used for the hidden input.

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-side]`	'top' \| 'right' \| 'bottom' \| 'left'
`[data-align]`	'start' \| 'center' \| 'end'
`[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`

option

The individual combobox item

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 `option` is disabled.

Data Attributes

Data Attribute	Value
`[data-disabled]`	Present when the `option` is disabled.
`[data-selected]`	Present when the `option` is selected.
`[data-highlighted]`	Present when the element is highlighted.
`[data-melt-combobox-option]`	Present on all option 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.

group

A function which takes in a unique key to group options together.

Props

Prop	Default	Type / Description
`key`	-	`string` A unique key for the group.

Data Attributes

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

group-label

A function which takes in a unique key to group options together.

Props

Prop	Default	Type / Description
`key`	-	`string` A unique key for the group.

Data Attributes

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

arrow

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

Data Attributes

Data Attribute	Value
`[data-side]`	'top' \| 'right' \| 'bottom' \| 'left'
`[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