Combobox
An input with an associated popup containing a list of options. Commonly used for autocomplete functionality and command palettes.
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.
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.
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. |
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. |
onOpenChange | - | ChangeFn<boolean> A callback called when the value of the 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 |
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
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 |
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 |
IDs
Option | Description |
trigger | The writable store that represents the id of the |
menu | The writable store that represents the id of the |
label | The writable store that represents the id of the |
menu
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] |
|
[data-disabled] | Present when the |
[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 |
Data Attributes
Data Attribute | Value |
[data-disabled] | Present when the |
[data-selected] | Present when the |
[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] |
|
[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 |
On This Page