Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

MultiSelect

A multi-select listbox with removable chips and overflow.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Choose teams
0 teams selected:

Install

Run in your project
bunx --bun @getweini/cli@latest add multi-select

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Choose regions
0 regions selected:
Vue
<script setup lang="ts">
import { ref } from 'vue'
import MultiSelect from './components/ui/multi-select/MultiSelect.vue'
import MultiSelectContent from './components/ui/multi-select/MultiSelectContent.vue'
import MultiSelectOption from './components/ui/multi-select/MultiSelectOption.vue'
import MultiSelectTrigger from './components/ui/multi-select/MultiSelectTrigger.vue'
import MultiSelectValue from './components/ui/multi-select/MultiSelectValue.vue'

const regions = ref<string[]>([])
const messages = {
  listboxLabel: 'Region options',
  empty: 'No regions available',
  clear: 'Clear',
  clearSelection: 'Clear all regions',
  changeSelection: 'Change regions',
  removeSelection: (label: string) => `Remove ${label}`,
  overflow: (count: number) => `+${count}`,
  selectionSummary: (labels: readonly string[]) =>
    `${labels.length} regions selected: ${labels.join(', ')}`,
}
</script>

<template>
  <label id="regions-label" for="regions">Regions</label>
  <MultiSelect id="regions" aria-labelledby="regions-label" v-model="regions" :messages="messages">
    <MultiSelectTrigger><MultiSelectValue placeholder="Choose regions" /></MultiSelectTrigger>
    <MultiSelectContent>
      <MultiSelectOption value="LU">Luxembourg</MultiSelectOption>
      <MultiSelectOption value="BE">Belgium</MultiSelectOption>
    </MultiSelectContent>
  </MultiSelect>
</template>

Enter or Space toggles the focused option. Named fields submit repeated values; read them with FormData.getAll(name).

When to use it

Multiple regions

Choose several regions and submit repeated form values.

Compact tag filters

Limit visible chips while retaining a complete selection summary.

More examples

Region picker

All selection and removal text belongs to the application.

Region picker
<script setup lang="ts">
import { ref } from 'vue'
import MultiSelect from './components/ui/multi-select/MultiSelect.vue'

const regions = ref<string[]>([])
const options = [
  { label: 'Luxembourg', value: 'LU' },
  { label: 'Belgium', value: 'BE' },
]
const messages = {
  listboxLabel: 'Regions',
  empty: 'No regions',
  clear: 'Clear',
  clearSelection: 'Clear regions',
  changeSelection: 'Change regions',
  removeSelection: (label: string) => `Remove ${label}`,
  selectionSummary: (labels: readonly string[]) => `${labels.length} regions: ${labels.join(', ')}`,
  overflow: (count: number) => `+${count}`,
}
</script>
<template>
  <label for="regions">Regions</label>
  <MultiSelect
    id="regions"
    v-model="regions"
    :options="options"
    :messages="messages"
    name="regions"
    placeholder="Choose regions"
  />
</template>

Compact filters

The visible chip limit does not limit selected values.

Compact filters
<script setup lang="ts">
import { ref } from 'vue'
import MultiSelect from './components/ui/multi-select/MultiSelect.vue'

const tags = ref<string[]>(['design'])
const options = [
  { label: 'Design', value: 'design' },
  { label: 'Engineering', value: 'engineering' },
]
const messages = {
  listboxLabel: 'Tags',
  empty: 'No tags',
  clear: 'Clear',
  clearSelection: 'Clear tags',
  changeSelection: 'Change tags',
  removeSelection: (label: string) => `Remove ${label}`,
  selectionSummary: (labels: readonly string[]) => `${labels.length} tags: ${labels.join(', ')}`,
  overflow: (count: number) => `+${count}`,
}
</script>
<template>
  <label for="tags">Tags</label>
  <MultiSelect
    id="tags"
    v-model="tags"
    :options="options"
    :messages="messages"
    :max-visible-chips="2"
    clearable
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

MultiSelect

Complete API for MultiSelect
NameType or signatureDefaultWhat it does
modelValuemodelT[] | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
defaultValuepropT[] | undefinedNot setStarting value when the parent does not control the value.
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedNot setStarting open state when the parent does not control open.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
gappropnumber | undefined12Space in pixels between the trigger and floating content.
byprop((a: T, b: T) => boolean) | undefinedNot setCompare two values when identity is not enough, such as object options.
serializeprop((value: T) => string) | undefinedNot setTurn a selected value into the string submitted with a form.
optionspropreadonly SelectOption<T>[] | undefinedNot setChoices that a person can select.
messagespropMultiSelectMessagesRequiredCaller-owned labels and announcements for the default compound controls.
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
clearablepropboolean | undefinedNot setShow an action for clearing the selected value.
maxVisibleChipspropnumber | undefined1Number of selected chips to show before combining the rest.
changeevent[value: T[]]—Emitted after this value or state changes.
update:modelValueevent[value: T[]]—Requests a new model value from the parent.
update:openevent[open: boolean]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot(() => unknown) | undefinedOptionalContent shown inside MultiSelect.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of MultiSelect.
elementexposedHTMLButtonElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
openexposed(last?: boolean, pointer?: boolean) => Promise<void>—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.

MultiSelectContent

Complete API for MultiSelectContent
NameType or signatureDefaultWhat it does
widthpropstring | number | undefined"trigger"Choose the width of this content.
defaultslot() => unknownRequiredContent shown inside MultiSelectContent.

MultiSelectOption

Complete API for MultiSelectOption
NameType or signatureDefaultWhat it does
valuepropTRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
textValuepropstring | undefinedNot setPlain text used for search, typeahead, or an accessible label.
labelpropstring | undefinedNot setVisible or accessible name for this item.
defaultslot() => unknownRequiredContent shown inside MultiSelectOption.
indicatorslot(() => unknown) | undefinedOptionalContent for the indicator area of MultiSelectOption.

MultiSelectTrigger

Complete API for MultiSelectTrigger
NameType or signatureDefaultWhat it does
sizepropControlSize | undefinedNot setChoose the visual size. Medium is the usual default where available.
defaultslot() => unknownRequiredContent shown inside MultiSelectTrigger.

MultiSelectValue

Complete API for MultiSelectValue
NameType or signatureDefaultWhat it does
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
maxVisibleChipspropnumber | undefinedNot setNumber of selected chips to show before combining the rest.
removeLabelprop((label: string) => string) | undefinedNot setAccessible name for the remove action.
clearLabelpropstring | undefinedNot setAccessible name announced for the clear action.
defaultslot((props: { values: unknown[]; options: unknown[]; remove: (value: unknown) => void; clear: () => void; }) => unknown) | undefinedOptionalContent shown inside MultiSelectValue.
placeholderslot(() => unknown) | undefinedOptionalContent for the placeholder area of MultiSelectValue.
Public type definitions
Public types
// packages/frameworks/vue/components/multi-select/types.ts
// ------- IMPORTS -------

import type {
  ControlSize,
  SelectOption as LegacySelectOption,
  ListboxMessages,
} from '@getweini/vue/types'

// ------- TYPES -------

export interface MultiSelectMessages extends ListboxMessages {
  clear: string
  changeSelection: string
  removeSelection: (label: string) => string
  /** Own the entire sentence, including pluralization, list formatting, and required state. */
  selectionSummary: (labels: readonly string[], required: boolean) => string
  overflow: (count: number) => string
}

export interface MultiSelectProps<T = string> {
  modelValue?: T[]
  defaultValue?: T[]
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
  required?: boolean
  invalid?: boolean
  name?: string
  form?: string
  id?: string
  size?: ControlSize
  gap?: number
  by?: (a: T, b: T) => boolean
  serialize?: (value: T) => string
  options?: readonly LegacySelectOption<T>[]
  /** Caller-owned labels and announcements for the default compound controls. */
  messages: MultiSelectMessages
  placeholder?: string
  clearable?: boolean
  maxVisibleChips?: number
}

export interface MultiSelectTriggerProps {
  size?: ControlSize
}
export interface MultiSelectValueProps {
  placeholder?: string
  maxVisibleChips?: number
  removeLabel?: (label: string) => string
  clearLabel?: string
}
export interface MultiSelectContentProps {
  width?: 'trigger' | string | number
}
export interface MultiSelectOptionProps<T = string> {
  value: T
  disabled?: boolean
  textValue?: string
  label?: string
}

// ------- EXPORTS -------

export type MultiSelectOption<T = unknown> = LegacySelectOption<T>


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • Named controls submit repeated values; read them with FormData.getAll(name).
  • maxVisibleChips changes the trigger display only, not the selected model.

Accessibility and localization

  • Localize every messages field, including chip removal and the full selection summary.

Source contract and editing guidance