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.

Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started

TIP

This component can be translated globally using the MazUi plugin.

Basic usage

Select color

selectedValue:

<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

Choose options

selectedValues:

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

Search

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

TIP

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

View code

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

INFO

You can adjust the search results by using search-threshold where 1 is a perfect match and 0 is a match with any character

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

Select color

<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

<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

Select options

<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

Select color

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

Size

Select color

Select color

Select color

Select color

Select color

Select color

<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

Select color

<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

<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"
    :options="options"
    :color="selectedValueCustom"
    option-value-key="valueOption"
    option-label-key="labelOption"
    option-input-value-key="inputLabel"
    search
  />
</template>

Types

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

Accessibility

MazSelect follows the WAI-ARIA combobox pattern 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).

Tips

TIP

This component use MazInput, so it inherits all his props

Props

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

Events

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

Slots

Name	Description	Bindings
start-icon	Add a custom inline-start icon (left in LTR, right in RTL)	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)	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	label string | number | true - the label of the optgroup
default	Custom option	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