---
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](/forms/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](/forms/select#style), [variant](/forms/select#style), [size](/forms/select#size), [placeholder](/forms/select#placeholder), [icon](/forms/select#icon), [disabled](/forms/select#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](/forms/select#icon) 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](https://headlessui.com/vue/combobox) component instead of [Listbox](https://headlessui.com/vue/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](#create-option) section.
::

## Props

:component-props

## Preset

:component-preset