---
title: "MazSelect - with \"multiple\" options"
description: "MazSelect is a standalone component that replaces the standard html input select with a beautiful design system. There are many options like multiple values, search text field, custom templates options, colors, sizes, disabled, loading, error, warning, valid states, error messages, and icons."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-select"
---

# MazSelect - with "multiple" options

> MazSelect is a standalone component that replaces the standard html input select with a beautiful design system. There are many options like multiple values, search text field, custom templates options, colors, sizes, disabled, loading, error, warning, valid states, error messages, and icons.

- Package: `maz-ui`
- Import: `import MazSelect from 'maz-ui/components/MazSelect'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-select

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

**Tip:**

This component can be translated globally using the [MazUi](https://maz-ui.com/ecosystem/translations.md) plugin.

## Basic usage

```vue
<script setup lang="ts">
import MazSelect from 'maz-ui/components/MazSelect'
import { ref } from 'vue'

const selectedValue = ref()
</script>

<template>
  <MazSelect
    v-model="selectedValue"
    label="Select color"
    :color="color"
    :options="['primary', 'secondary', 'info', 'success', 'destructive', 'warning']"
  />

  selectedValue: {{ selectedValue }}
</template>
```

## Multiple

```html
<MazSelect v-model="selectedValues" :options="colors" label="Choose options" multiple />
```

## Search

Use `search` property to add a search input in the options list.

The search is a fuzzy search (the [fuzzySearch](https://maz-ui.com/ecosystem/utils/fuzzy-search.md) helper of `@maz-ui/utils`, loaded only with `search`): it finds the prefixes, the words in any order, the initials ("nwz" finds "New Zealand"), the typos ("Franse" finds "France"), whatever the accents and the case. It searches the label, the input value and the value of the options. The best matches come first; with optgroups, the matched options keep the order of the list under their group.

**Tip:**

You can use your own template to replace the empty icon when no results are found

**Details: View code**

```html
<MazSelect>
  <template #no-results>
    <div class="p-4 text-center">No result</div>
  </template>
</MazSelect>
```

**Note:**

`search-threshold` is the tolerance to typos: the minimal similarity (from 0 to 1) of a whole option with the query, for the options that do not contain it. `1` disables the typo tolerance, `0` matches any option (default `0.75`)

```html
<MazSelect :search-threshold="0.75" :options="[...]" />
```

```html
<MazSelect v-model="selectedValue" label="Select color" :options="colors" search />
```

### Custom search function

You can provide your own search function to customize the search behavior

```vue
<script lang="ts" setup>
import MazSelect from 'maz-ui/components/MazSelect'

const selectedValue = ref()

function customSearchFunction(query: string, options: typeof colors) {
  return options.filter(
    option => option.label.toLowerCase().includes(query.toLowerCase())
  )
}
</script>

<template>
  <MazSelect
    v-model="selectedValue"
    placeholder="Select color"
    :options="colors"
    search
    :search-function="customSearchFunction"
  />
</template>
```

## Opt Group

Group your options like a native optgroup

```vue
<script setup lang="ts">
import { ref } from 'vue'
const selectedValue = ref()
const optGroup = [
  { label: 'Basic colors', options: ['primary', 'secondary', 'destructive'] },
  { label: 'Custom colors', options: [{ label: 'third', value: 'third' }] },
]
</script>

<template>
  <MazSelect
    v-model="optGroupValue"
    label="Select option"
    :options="optGroup"
    multiple
  />
</template>
```

## Disabled

```html
<MazSelect
  label="Select color"
  v-model="selectedValue"
  :options="colors"
  disabled
/>
```

## Size

```vue
<template>
  <MazSelect
    v-for="size in sizes"
    :key="size"
    label="Select color"
    v-model="selectedValue"
    :options="colors"
    :size="size"
  />
</template>

<script lang="ts" setup>
  import { ref } from 'vue'
  import { MazSelect, type MazSize } from 'maz-ui/components'

  const selectedValue = ref()

  const sizes: MazSize[] = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
</script>
```

## Custom template options

Customize the options list with your own template

```vue{6}
<template>
  <MazSelect
  label="Select color"
  v-model="selectedUser"
  :options="customTemplateOptions"
  v-slot="{ option, isSelected }"
  search
>
  <div class="flex items-center" style="width: 100%; gap: 1rem">
    <MazAvatar size="0.8rem" :src="option.picture" />
    <strong>
      {{ option.label }}
    </strong>
    </div>
  </MazSelect>
</template>

<script lang="ts" setup>
  import { ref } from 'vue'
  import { MazSelect, MazAvatar } from 'maz-ui/components'

  const selectedUser = ref()

  const customTemplateOptions = [
    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=JamesSmile', label: 'James Smile', value: 1 },
    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=BradSmile', label: 'Brad Smile', value: 2 },
    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=CedricSmile', label: 'Cedric Smile', value: 3 },
    { picture: 'https://api.dicebear.com/7.x/big-smile/svg?backgroundColor=1d90ff&seed=HarrySmile', label: 'Harry Smile', value: 4 },
  ]
</script>
```

## Custom options model

By default, the options should be an array of `{ value: any, label: string }`

If you want custom keys of these options, you can use:

- `option-value-key` to override the key of the value in your option
- `option-label-key` to override the key of the label to show in the option list
- `option-input-value-key` to override the key of the value to show in the input

### Example

```vue
<script lang="ts" setup>
import { ref } from 'vue'
const selectedValueCustom = ref('destructive')

const customOptions = [
  { valueOption: 'primary', labelOption: 'primary label', inputLabel: 'primary input', },
  { valueOption: 'secondary', labelOption: 'secondary label', inputLabel: 'secondary input', },
  { valueOption: 'info', labelOption: 'info label', inputLabel: 'info input', },
  { valueOption: 'success', labelOption: 'success label', inputLabel: 'success input', },
  { valueOption: 'warning', labelOption: 'warning label', inputLabel: 'warning input', },
  { valueOption: 'destructive', labelOption: 'destructive label', inputLabel: 'destructive input', },
  { valueOption: 'white', labelOption: 'white label', inputLabel: 'white input', },
  { valueOption: 'black', labelOption: 'black label', inputLabel: 'black input', },
]
</script>

<template>
  <MazSelect
    v-model="selectedValueCustom"
    label="Select a color"
    :options="options"
    :color="selectedValueCustom"
    option-value-key="valueOption"
    option-label-key="labelOption"
    option-input-value-key="inputLabel"
    search
  />
</template>
```

### Types

```ts
type ModelValueSimple = string | number | null | undefined | boolean
```

## Accessibility

`MazSelect` follows the [WAI-ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) with a listbox popup:

- The input is a `combobox` (`aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`).
- The list is a `listbox` (`aria-multiselectable` in multiple mode) labelled by the `label`, `top-label` or `placeholder`, each option is an `option` with `aria-selected`.
- **Keyboard**: ↓ / ↑ / Space or a letter open the list, the arrows move between options, Home / End go to the first / last option, Enter selects, Esc closes.
- The labels read by screen readers (toggle button, empty results) come from `@maz-ui/translations` (`aria` namespace).

## MazSelect API

`import MazSelect from 'maz-ui/components/MazSelect'`

### Props

- `id` (`string`): The id of the select.
- `label` (`string`): The label of the select.
- `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
- `placeholder` (`string`): The placeholder of the select.
- `model-value` (`(Multiple extends true ? Value[] : Value)`, `v-model`): The value of the select.
- `options` (`Option[]`, required): The options of the select.
- `option-value-key` (`string`, default: `"value"`): The key of the option value.
- `option-label-key` (`string`, default: `"label"`): The key of the option label.
- `option-input-value-key` (`string`, default: `"label"`): The key of the option input value.
- `list-position` (`MazPopoverPosition`, default: `"auto"`): The position of the list (auto by default - will switch between bottom-start and top-start).
- `prefer-position` (`MazPopoverPreferPosition`, default: `"bottom-start"`): The prefer position of the list.
- `fallback-position` (`MazPopoverFallbackPosition`, default: `"top-start"`): The fallback position of the list.
- `item-height` (`number`): The height of the option list item.
- `max-list-height` (`number`, default: `240`): The max height of the option list.
- `max-list-width` (`number`): The max width of the option list.
- `min-list-height` (`number`): The min height of the option list.
- `min-list-width` (`number`): The min width of the option list.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`, default: `'md'`): The size of the select.
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the select.
- `search` (`boolean`): Display search input in option list.
- `search-function` (`((query: string, options: Option[]) => Option[] | undefined)`): Replace the default search function to provide a custom search function.
- `search-threshold` (`number`, default: `0.75`): Tolerance of the search to typos: the minimal similarity (from 0 to 1) of a whole option with the query, for the options that do not contain it. `1` disables the typo tolerance, `0` matches any option.
- `multiple` (`Multiple`, default: `false`): Enable the multiple selection.
- `required` (`boolean`): Make the input required in the form.
- `disabled` (`boolean`): Disable the component.
- `block` (`boolean`): The input will be displayed in full width.
- `autocomplete` (`string`, default: `"off"`): The autocomplete attribute of the input.
- `translations` (`Partial<{ searchPlaceholder: string; }>`, default: `{ searchPlaceholder: 'Search in options', }`): The translations of the component.
- `format-input-value` (`((value: Multiple extends true ? Value[] : Value) => string)`): The function to format the input value.
- `transition` (`string`, default: `"scale-fade"`): The transition name of the panel list options.
- `open` (`boolean`, default: `false`, `v-model:open`)

### Events

- `@update:model-value` (payload: `value: Multiple extends true ? Value[] : Value`): On model value update, returns the new value
- `@open`: On list is opened
- `@close`: On list is closed
- `@input` (payload: `value: Event`): On input value
- `@blur` (payload: `value: Event`): On input blur
- `@change` (payload: `value: Event`): On input change value
- `@focus` (payload: `value?: Event | undefined`): On input focus
- `@selected-option` (payload: `value: Option`): On selected value, returns the option object
- `@update:open` (payload: `value: boolean`)

### Slots

- `#start-icon`: Add a custom inline-start icon (left in LTR, right in RTL) Bindings: `isOpen: false` (Current open state of the popover), `close: () => void` (Function to close the popover), `open: () => void` (Function to open the popover), `toggle: () => void` (Function to toggle the popover).
- `#end-icon`: Add and replace a custom inline-end icon (right in LTR, left in RTL) Bindings: `isOpen: false` (Current open state of the popover), `close: () => void` (Function to close the popover), `open: () => void` (Function to open the popover), `toggle: () => void` (Function to toggle the popover).
- `#no-results`: No results slot - Displayed when no results corresponding with search query
- `#optgroup`: Custom optgroup label Bindings: `label: string` (the label of the optgroup).
- `#default`: Custom option Bindings: `option: Option` (the option object), `isSelected: boolean` (if the option is selected), `isOpen: false` (if the popover is open), `close: () => void` (function to close the popover), `open: () => void` (function to open the popover), `toggle: () => void` (function to toggle the popover).
