Skip to main content

Select

Presents a selection of choices to the user, activated by a button.

Features

  • Full keyboard navigation
  • Can be controlled or uncontrolled
  • Typeahead support
  • Optional arrow component
  • Custom positioning

Anatomy

  • Trigger: The button that opens/closes the select menu
  • Menu: The popover select menu
    • Option: The individual select options
    • Label: The label for the input
    • Arrow: An optional arrow element which points to the menu's input
    • Group: An optional group and group label element which can be used to group options

Usage

To create an select, use the createSelect builder function. Follow the anatomy or the example at the top of this page to create your select.

Example components

Multi-select

A multi-select is a select that allows the user to select multiple options. To create a multi-select, simply set the multiple prop to true on the createSelect builder.

Change options with keyboard

Using custom event listeners, you can customize what the keyboard does when interacting with the trigger. In this example, we use the on:keydown event listener to change the selected option when the user presses the up or down arrow keys, instead of opening the menu.

API Reference

createSelect

The builder function used to create the select component.

Props

Prop Default Type / Description
defaultSelected -
SelectOption<unknown>

The initial selected option.
selected -
Writable<SelectOption<unknown>>

A writable store that can be used to get or update or the selected option.

See Bring Your Own Store

onSelectedChange -
ChangeFn<SelectOption<unknown>>

A callback that is called when the selected option changes.

See Change Functions

required false
boolean

Whether or not the select is required.
disabled false
boolean

Whether or not the select is disabled.
arrowSize 8
number

The size of the arrow which points to the trigger in pixels.
preventScroll true
boolean

Whether or not to prevent scrolling of the document when the select is open.
loop false
boolean

Whether or not the focus should loop back to the first item when the last item is reached.
escapeBehavior 'close'
'close' | 'ignore' | 'defer-otherwise-close' | 'defer-otherwise-ignore'

Defines how the select reacts when the Escape key is pressed.

  • close: Closes the select immediately.
  • ignore: Prevents the select 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.

    		•
    closeOnOutsideClick true
    boolean

    Whether or not to close the select when the user clicks outside of it.
    preventTextSelectionOverflow true
    boolean

    Whether to prevent text selection overflowing the select when it is the top layer.
    portal body
    string | HTMLElement | null

    The element or selector to render the select 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.
    forceVisible false
    boolean

    Whether or not to force the select to always be visible. This is useful for custom transitions and animations using conditional blocks.
    positioning placement: 'bottom'

    A configuration object which determines how the floating element is positioned relative to the trigger.
    name -
    string

    The name to be used for the select input.
    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
    multiple false
    boolean

    Whether or not the select is a multiple select.
    defaultOpen false
    boolean

    Whether the select is open by default or not.
    open -
    Writable<boolean>

    A writable store that controls whether or not the select 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

    ids -
    Record<'trigger' | 'menu' | 'label', string>

    Override the internally generated ids for the elements.

    Elements

    Element Description

    The builder store used to create the select trigger.

    The builder store used to create the select menu.

    The builder store used to create the select options.

    The builder store used to create the select hidden input.

    The builder store used to create the select label.

    The builder store used to create the select separator.

    The builder store used to create the select group.

    The builder store used to create the select group label.

    The builder store used to create the select arrow.

    States

    State Description
    open

    A writable store that returns whether or not the select is open.
    selected

    A writable store whose value is the selected option.
    selectedLabel

    A readable store whose value is the selected option's label.

    Helpers

    Helper Description
    isSelected

    A derived store that returns whether or not the given value is selected.

    Options

    Option Description
    required

    Whether or not the select is required.
    disabled

    Whether or not the select is disabled.
    arrowSize

    The size of the arrow which points to the trigger in pixels.
    preventScroll

    Whether or not to prevent scrolling of the document when the select is open.
    loop

    Whether or not the focus should loop back to the first item when the last item is reached.
    escapeBehavior

    Defines how the select reacts when the Escape key is pressed.

  • close: Closes the select immediately.
  • ignore: Prevents the select 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.

    		•
    closeOnOutsideClick

    Whether or not to close the select when the user clicks outside of it.
    preventTextSelectionOverflow

    Whether to prevent text selection overflowing the select when it is the top layer.
    portal

    The element or selector to render the select 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.
    forceVisible

    Whether or not to force the select to always be visible. This is useful for custom transitions and animations using conditional blocks.
    positioning

    A configuration object which determines how the floating element is positioned relative to the trigger.
    name

    The name to be used for the select input.
    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.

    trigger

    The element which opens/closes the select.

    Data Attributes

    Data Attribute Value
    [data-state]

    'open' | 'closed'
    [data-disabled]

    Present when the select is disabled.
    [data-melt-select-trigger]

    Present on all trigger elements.

    Custom Events

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

    label

    The label element

    Data Attributes

    Data Attribute Value
    [data-melt-select-label]

    Present on all label elements.

    Custom Events

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

    menu

    The menu element

    Data Attributes

    Data Attribute Value
    [data-side]

    'top' | 'right' | 'bottom' | 'left'
    [data-align]

    'start' | 'center' | 'end'
    [data-melt-select-menu]

    Present on all menu elements.

    Custom Events

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

    option

    The option elements

    Props

    Prop Default Type / Description
    label -
    string

    The label of the option.
    value * -
    unknown

    The value of the option.
    disabled false
    boolean

    Whether or not the option is disabled.

    Data Attributes

    Data Attribute Value
    [data-melt-select-option]

    Present on all option elements.

    Custom Events

    Event Value
    m-click (e: ) => void
    m-keydown (e: ) => void
    m-pointermove (e: ) => void
    m-pointerleave (e: ) => void
    m-focusin (e: ) => void
    m-focusout (e: ) => void

    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-select-group]

    Present on all group elements.

    groupLabel

    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-select-group-label]

    Present on all group-label elements.

    separator

    An optional separator element

    Data Attributes

    Data Attribute Value
    [data-melt-select-separator]

    Present on all separator elements.

    arrow

    The optional arrow element

    Data Attributes

    Data Attribute Value
    [data-side]

    'top' | 'right' | 'bottom' | 'left'
    [data-arrow]

    'true'
    [data-melt-select-arrow]

    Present on all arrow elements.

    hidden-input

    The hidden input element. Used for form submission.

    Data Attributes

    Data Attribute Value
    [data-melt-select-hidden-input]

    Present on all hidden-input elements.

    Accessibility

    Adheres to the ListBox WAI-ARIA design pattern

    Key Behavior
    Space

    When focus is on the trigger, opens the select and focuses the selected option. When focus is on an option, selects the focused option.
    Enter

    When focus is on the trigger, opens the select and focuses the selected option. When focus is on an option, selects the focused option.
    ArrowDown

    When focus is on the trigger, opens the select. When focus is on an option, moves focus to the next option.
    ArrowUp

    When focus is on the trigger, opens the select. When focus is on an option, moves focus to the previous option.
    Esc

    Closes the select and moves focus to the trigger.