Select

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

View code

Favorite Flavor

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.

View code

Favorite Flavor

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.

View code

Favorite Flavor

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
`trigger`	The builder store used to create the select trigger.
`menu`	The builder store used to create the select menu.
`option`	The builder store used to create the select options.
`hiddenInput`	The builder store used to create the select hidden input.
`label`	The builder store used to create the select label.
`separator`	The builder store used to create the select separator.
`group`	The builder store used to create the select group.
`groupLabel`	The builder store used to create the select group label.
`arrow`	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`

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

On This Page