ui/docs/content/3.forms/4.select-menu.md

title, description, links

title	description	links
SelectMenu	Display a select menu with advanced features.	label icon to GitHub i-simple-icons-github https://github.com/nuxt/ui/blob/dev/src/runtime/components/forms/SelectMenu.vue label icon to Listbox i-simple-icons-headlessui https://headlessui.com/vue/listbox

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.

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

:component-example{component="select-menu-example-basic" :componentProps='{"class": "w-full lg:w-40"}'}

Multiple

You can use the multiple prop to select multiple values.

:component-example{component="select-menu-example-multiple" :componentProps='{"class": "w-full lg:w-40"}'}

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.

:component-example{component="select-menu-example-objects" :componentProps='{"class": "w-full lg:w-40"}'}

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.

:component-example{component="select-menu-example-objects-value-attribute" :componentProps='{"class": "w-full lg:w-40"}'}

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.

::component-card

baseProps: class: 'w-full lg:w-40' placeholder: 'Select a person' options: ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer'] props: selectedIcon: 'i-heroicons-hand-thumb-up-solid' excludedProps:

• selectedIcon

---

::

::callout{icon="i-heroicons-light-bulb"} Learn how to customize icons from the Select component. ::

Search

Use the searchable prop to enable search.

Use the searchable-placeholder prop to set a different placeholder.

This will use Headless UI Combobox component instead of Listbox.

::component-card

baseProps: class: 'w-full lg:w-40' placeholder: 'Select a person' options: ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer'] props: searchable: true searchablePlaceholder: 'Search a person...'

::

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.

:component-example{component="select-menu-example-async-search" :componentProps='{"class": "w-full lg:w-40"}'}

Create option

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.

:component-example{component="select-menu-example-creatable" :componentProps='{"class": "w-full lg:w-40"}'}

Popper

Use the popper prop to customize the popper instance.

Arrow

:component-example{component="select-menu-example-arrow"}

Placement

:component-example{component="select-menu-example-placement"}

Offset

:component-example{component="select-menu-example-offset"}

Slots

label

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

:component-example{component="select-menu-example-multiple-slot" :componentProps='{"class": "w-full lg:w-40"}'}

default

You can also override the #default slot entirely.

:component-example{component="select-menu-example-button" :componentProps='{"class": "w-full lg:w-40"}'}

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.

:component-example{component="select-menu-example-option-slot" :componentProps='{"class": "w-full lg:w-40"}'}

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.

:component-example{component="select-menu-example-option-empty-slot" :componentProps='{"class": "w-full lg:w-40"}'}

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.

::callout{icon="i-heroicons-light-bulb"} An example is available in the Create option section. ::

Props

:component-props

Config

:component-preset