Multiple regions
Choose several regions and submit repeated form values.
Components / Forms
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.
bunx --bun @getweini/cli@latest add multi-selectImport 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.
<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).
Choose several regions and submit repeated form values.
Limit visible chips while retaining a complete selection summary.
All selection and removal text belongs to the application.
<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>The visible chip limit does not limit selected values.
<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>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.
| Name | Type or signature | Default | What it does |
|---|---|---|---|
modelValuemodel | T[] | undefined | Not set | Current value. Use v-model to keep it in sync with your page. |
defaultValueprop | T[] | undefined | Not set | Starting value when the parent does not control the value. |
openmodel | boolean | undefined | Not set | Current open state. Use v-model:open to keep it in sync with your page. |
defaultOpenprop | boolean | undefined | Not set | Starting open state when the parent does not control open. |
disabledprop | boolean | undefined | Not set | Prevent interaction and show the disabled state. |
requiredprop | boolean | undefined | Not set | Ask the browser to require a value before form submission. |
invalidprop | boolean | undefined | Not set | Show the invalid state; also provide a visible error message. |
nameprop | string | undefined | Not set | Name used when this control submits a value with a form. |
formprop | string | undefined | Not set | Associate the control with a form by its ID. |
idprop | string | undefined | Not set | Give the control an ID so a label or description can refer to it. |
sizeprop | ControlSize | undefined | "md" | Choose the visual size. Medium is the usual default where available. |
gapprop | number | undefined | 12 | Space in pixels between the trigger and floating content. |
byprop | ((a: T, b: T) => boolean) | undefined | Not set | Compare two values when identity is not enough, such as object options. |
serializeprop | ((value: T) => string) | undefined | Not set | Turn a selected value into the string submitted with a form. |
optionsprop | readonly SelectOption<T>[] | undefined | Not set | Choices that a person can select. |
messagesprop | MultiSelectMessages | Required | Caller-owned labels and announcements for the default compound controls. |
placeholderprop | string | undefined | Not set | Hint shown when no value has been entered or selected. |
clearableprop | boolean | undefined | Not set | Show an action for clearing the selected value. |
maxVisibleChipsprop | number | undefined | 1 | Number 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) | undefined | Optional | Content shown inside MultiSelect. |
prefixslot | (() => unknown) | undefined | Optional | Content shown before the main label or value. |
suffixslot | (() => unknown) | undefined | Optional | Content shown after the main label or value. |
errorslot | ((props: { message: string; messages: string[]; }) => unknown) | undefined | Optional | Content for the error area of MultiSelect. |
elementexposed | HTMLButtonElement | 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. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
widthprop | string | number | undefined | "trigger" | Choose the width of this content. |
defaultslot | () => unknown | Required | Content shown inside MultiSelectContent. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
valueprop | T | Required | Value represented by this control or option. |
disabledprop | boolean | undefined | Not set | Prevent interaction and show the disabled state. |
textValueprop | string | undefined | Not set | Plain text used for search, typeahead, or an accessible label. |
labelprop | string | undefined | Not set | Visible or accessible name for this item. |
defaultslot | () => unknown | Required | Content shown inside MultiSelectOption. |
indicatorslot | (() => unknown) | undefined | Optional | Content for the indicator area of MultiSelectOption. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
sizeprop | ControlSize | undefined | Not set | Choose the visual size. Medium is the usual default where available. |
defaultslot | () => unknown | Required | Content shown inside MultiSelectTrigger. |
| Name | Type or signature | Default | What it does |
|---|---|---|---|
placeholderprop | string | undefined | Not set | Hint shown when no value has been entered or selected. |
maxVisibleChipsprop | number | undefined | Not set | Number of selected chips to show before combining the rest. |
removeLabelprop | ((label: string) => string) | undefined | Not set | Accessible name for the remove action. |
clearLabelprop | string | undefined | Not set | Accessible name announced for the clear action. |
defaultslot | ((props: { values: unknown[]; options: unknown[]; remove: (value: unknown) => void; clear: () => void; }) => unknown) | undefined | Optional | Content shown inside MultiSelectValue. |
placeholderslot | (() => unknown) | undefined | Optional | Content for the placeholder area of MultiSelectValue. |
// 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;
}