Skip to main content

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.

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.

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

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

    menu

    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.