mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-15 04:29:37 +01:00
289 lines
7.8 KiB
Markdown
289 lines
7.8 KiB
Markdown
---
|
|
title: SelectMenu
|
|
description: Display a select menu with advanced features.
|
|
links:
|
|
- label: GitHub
|
|
icon: i-simple-icons-github
|
|
to: https://github.com/nuxt/ui/blob/dev/src/runtime/components/forms/SelectMenu.vue
|
|
- label: 'Listbox'
|
|
icon: i-simple-icons-headlessui
|
|
to: 'https://headlessui.com/vue/listbox'
|
|
---
|
|
|
|
## Usage
|
|
|
|
The `SelectMenu` component renders by default a [Select](/components/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](/components/select#style), [variant](/components/select#style), [size](/components/select#size), [placeholder](/components/select#placeholder), [icon](/components/select#icon), [disabled](/components/select#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.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-basic'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
### Multiple
|
|
|
|
You can use the `multiple` prop to select multiple values.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-multiple'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
### 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-48'
|
|
---
|
|
::
|
|
|
|
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-48'
|
|
---
|
|
::
|
|
|
|
### 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-48'
|
|
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](/components/select#icon) component.
|
|
::
|
|
|
|
## Searchable
|
|
|
|
Use the `searchable` prop to enable search.
|
|
|
|
Use the `searchable-placeholder` prop to set a different placeholder.
|
|
|
|
This will use Headless UI [Combobox](https://headlessui.com/vue/combobox) component instead of [Listbox](https://headlessui.com/vue/listbox).
|
|
|
|
::component-card
|
|
---
|
|
baseProps:
|
|
class: 'w-full lg:w-48'
|
|
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...'
|
|
---
|
|
::
|
|
|
|
### 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.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-search-attributes'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
### 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`.
|
|
|
|
::component-card
|
|
---
|
|
baseProps:
|
|
class: 'w-full lg:w-48'
|
|
placeholder: 'Select a person'
|
|
searchable: true
|
|
searchablePlaceholder: 'Search a person...'
|
|
options: ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer']
|
|
props:
|
|
clearSearchOnClose: true
|
|
---
|
|
::
|
|
|
|
### Control the query
|
|
|
|
Use a `v-model:query` to control the search query.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-search-query'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
### 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-search-async'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
## 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.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-creatable'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
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.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-creatable-always'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
## 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-48'
|
|
---
|
|
::
|
|
|
|
### `default`
|
|
|
|
You can also override the `#default` slot entirely.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-button'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
### `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-48'
|
|
---
|
|
::
|
|
|
|
### `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-48'
|
|
---
|
|
::
|
|
|
|
### `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](#create-option) section.
|
|
::
|
|
|
|
### `empty`
|
|
|
|
Use the `#empty` slot to customize the content displayed when there is no options. Defaults to `No options.`.
|
|
|
|
::component-example
|
|
---
|
|
component: 'select-menu-example-empty-slot'
|
|
componentProps:
|
|
class: 'w-full lg:w-48'
|
|
---
|
|
::
|
|
|
|
## Props
|
|
|
|
:component-props
|
|
|
|
## Config
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
Use the `ui` prop to override the select config and the `uiMenu` prop to override the menu config.
|
|
::
|
|
|
|
::tabs{:selectedIndex="1"}
|
|
:component-preset{label="Select (ui)" slug="Select"}
|
|
:component-preset{label="SelectMenu (uiMenu)"}
|
|
::
|