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
    • 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.

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.

Group

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

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 | null

The element or selector to render the combobox into. Nested floating elements are automatically rendered into their parent if not specified. Pass in null to disable portalling.

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

The builder store used to create the collapsible menu.

The builder store used to create the collapsible input.

The builder store used to create the menu item.

The builder store used to create the label for the combobox.

The builder store used to create the combobox group.

The builder store used to create the combobox group label.

The builder store used to create the combobox hidden input.

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.

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. Pass in null to disable portalling.

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.

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-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.