SelectMenu

Usage

The SelectMenu component renders by default a Select component and is based on the ui.select preset. You can use most of the Select props to configure the display if you don't want to override the default slot such as color, variant, size, placeholder, icon, disabled, etc.

You can use the ui prop like the Select component to override the default config. The uiMenu prop can be used to override the default menu config.

Like the Select component, you can use the options prop to pass an array of strings or objects.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Multiple

You can use the multiple prop to select multiple values.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Objects

You can pass an array of objects to options and either compare on the whole object or use the by prop to compare on a specific key. You can configure which field will be used to display the label through the option-attribute prop that defaults to label. Additionally, you can use dot notation (e.g., user.name) to access nested object properties.

benjamincanac

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

If you only want to select a single object property rather than the whole object as value, you can set the value-attribute property. This prop defaults to null.The value of the value-attribute field in options must be unique.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Icon

Use the selected-icon prop to set a different icon or change it globally in ui.selectMenu.default.selectedIcon. Defaults to i-heroicons-check-20-solid.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Searchable

Use the searchable prop to enable search.

Use the searchable-placeholder prop to set a different placeholder or globally through the ui.selectMenu.default.searchablePlaceholder.label config. Defaults to Search....

This will use Headless UI Combobox component instead of Listbox.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Attributes

Use the search-attributes prop with an array of property names to search on each option object. Nested attributes can be accessed using dot.notation. When the property value is an array or object, these are cast to string so these can be searched within.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Clear on close

By default, the search query will be kept after the menu is closed. To clear it on close, set the clear-search-on-close prop.

You can also configure this globally through the ui.selectMenu.default.clearSearchOnClose config. Defaults to false.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Control the query

Use a v-model:query to control the search query.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Async search

Pass a function to the searchable prop to customize the search behavior and filter options according to your needs. The function will receive the query as its first argument and should return an array.

Use the debounce prop to adjust the delay of the function.

Use the searchableLazy prop to control the immediacy of data requests.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Creatable

Use the creatable prop to enable the creation of new options when the search doesn't return any results (only works with searchable).

Try to search for something that doesn't exist in the example below.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

However, if you want to create options despite search query (apart from exact match), you can set the show-create-option-when prop to 'always'.

You can also configure this globally through the ui.selectMenu.default.showCreateOptionWhen config. Defaults to empty.

Try to search for something that exists in the example below, but not an exact match.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Pass a function to the show-create-option-when prop to control wether or not to show the create option. This function takes two arguments: the query (as the first argument) and an array of current results (as the second argument). It should return true to display the create option.

The example below shows how to make the create option visible when the query is at least three characters long and does not exactly match any of the current results (case insensitive).

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Popper

Use the popper prop to customize the popper instance.

Arrow

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Placement

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Offset

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Slots

label

You can override the #label slot and handle the display yourself.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

default

You can also override the #default slot entirely.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

option

Use the #option slot to customize the option content. You will have access to the option, active and selected properties in the slot scope.

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

option-empty

Use the #option-empty slot to customize the content displayed when the searchable prop is true and there is no options. You will have access to the query property in the slot scope.

You can also configure this globally through the ui.selectMenu.default.optionEmpty.label config. The token {query} will be replaced by query property. Defaults to No results for "{query}"..

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

option-create

Use the #option-create slot to customize the content displayed when the creatable prop is true and there is no options. You will have access to the query property in the slot scope.

empty

Use the #empty slot to customize the content displayed when there is no options.

You can also configure this globally through the ui.selectMenu.default.empty.label config. Defaults to No options..

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

Props

Config

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}

{
  "message": "You should use slots with <ContentRenderer>",
  "value": {},
  "excerpt": false,
  "tag": "div"
}