Large country list
Filter options by visible labels and alternate keywords.
Components / Forms
An editable, typo-tolerant input that filters a listbox and stores the selected option value.
Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.
bunx --bun @getweini/cli@latest add comboboxImport 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 Combobox from './components/ui/combobox/Combobox.vue'
const country = ref<string>()
const countries = [
{ label: 'Luxembourg', value: 'LU', keywords: ['Grand Duchy'] },
{ label: 'Belgium', value: 'BE' },
{ label: 'France', value: 'FR' },
]
const messages = {
listboxLabel: 'Countries',
empty: 'No matches',
clearSelection: 'Clear country',
}
</script>
<template>
<label for="country">Country</label>
<Combobox
id="country"
v-model="country"
:options="countries"
:messages="messages"
name="country"
clearable
/>
</template>Search matches full-text terms across labels and keywords, tolerates common typing mistakes by default, and can be made strict with typoTolerant=false. Arrow keys move the active option without committing, Enter selects, and Escape restores the selected label.
Filter options by visible labels and alternate keywords.
Control query text separately from the committed option value.
Keywords help people find a value using another common name.
<script setup lang="ts">
import { ref } from 'vue'
import Combobox from './components/ui/combobox/Combobox.vue'
const country = ref<string>()
const options = [
{ label: 'Luxembourg', value: 'LU', keywords: ['Grand Duchy'] },
{ label: 'Belgium', value: 'BE' },
]
const messages = {
listboxLabel: 'Countries',
empty: 'No countries match',
clearSelection: 'Clear country',
}
</script>
<template>
<label for="country">Country</label>
<Combobox
id="country"
v-model="country"
:options="options"
:messages="messages"
name="country"
clearable
/>
</template>Type At, then quickly replace it with Be. Watch for Searching projects… in the list, then check that Beacon is the result.
<script setup lang="ts">
import { ref, useId, watch } from 'vue'
import Combobox from './components/ui/combobox/Combobox.vue'
const id = useId()
const project = ref<string>()
const query = ref('')
const projects = [
{ label: 'Atlas', value: 'atlas' },
{ label: 'Atelier', value: 'atelier' },
{ label: 'Beacon', value: 'beacon' },
]
const options = ref(projects)
const loading = ref(false)
const messages = {
listboxLabel: 'Projects',
empty: 'No projects match',
clearSelection: 'Clear project',
loading: 'Searching projects…',
}
watch(query, (value, _previous, onCleanup) => {
loading.value = true
const timer = setTimeout(() => {
options.value = projects.filter((option) =>
option.label.toLowerCase().includes(value.trim().toLowerCase()),
)
loading.value = false
}, 1000)
onCleanup(() => clearTimeout(timer))
})
</script>
<template>
<label :for="id">Project</label>
<Combobox
:id="id"
v-model="project"
v-model:query="query"
:options="options"
:messages="messages"
:loading="loading"
:typo-tolerant="false"
/>
</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 |
|---|---|---|---|
optionsprop | readonly ComboboxOption<T>[] | Required | Choices that a person can select. |
messagesprop | ComboboxMessages | Required | Supply the text this component displays for its built-in actions and states. |
idprop | string | undefined | Not set | Give the control an ID so a label or description can refer to it. |
placeholderprop | string | undefined | Not set | Hint shown when no value has been entered or selected. |
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. |
sizeprop | ControlSize | undefined | "md" | Choose the visual size. Medium is the usual default where available. |
disabledprop | boolean | undefined | Not set | Prevent interaction and show the disabled state. |
readonlyprop | boolean | undefined | Not set | Show the value while preventing edits. |
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. |
clearableprop | boolean | undefined | Not set | Show an action for clearing the selected value. |
loadingprop | boolean | undefined | Not set | Show that an action is in progress and prevent repeat activation. |
typoTolerantprop | boolean | undefined | true | Allow close spelling matches while searching options. |
autocompleteprop | "none" | "list" | undefined | "list" | Tell the browser which saved value can fill this field. |
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. |
modelValuemodel | T | undefined | Not set | Current value. Use v-model to keep it in sync with your page. |
querymodel | string | undefined | "" | Current search text used to filter choices. |
clearevent | [] | — | Emitted when the user clears the value. |
closeevent | [] | — | Emitted when close happens. |
openevent | [] | — | Emitted when open happens. |
update:modelValueevent | [value: T | undefined] | — | Requests a new model value from the parent. |
update:queryevent | [value: string] | — | Requests a new query value from the parent. |
optionslot | ((props: { option: ComboboxOption<T>; active: boolean; selected: boolean; }) => unknown) | undefined | Optional | Content for the option area of Combobox. |
emptyslot | (() => unknown) | undefined | Optional | Content for the empty area of Combobox. |
loadingslot | (() => unknown) | undefined | Optional | Content for the loading area of Combobox. |
clearslot | (() => unknown) | undefined | Optional | Content for the clear area of Combobox. |
errorslot | ((props: { message: string; messages: string[]; }) => unknown) | undefined | Optional | Content for the error area of Combobox. |
inputexposed | HTMLInputElement | null | — | Access input from a component template ref. |
focusexposed | () => void | undefined | — | Move keyboard focus to this control. |
openexposed | () => void | — | Open this component from application code. |
closeexposed | () => void | — | Close this component from application code. |
clearexposed | () => void | — | Access clear from a component template ref. |
// packages/frameworks/vue/components/combobox/types.ts
import type { ControlSize } from '@getweini/vue/types'
export interface ComboboxOption<T = string> {
label: string
value: T
disabled?: boolean
keywords?: readonly string[]
}
export interface ComboboxMessages {
listboxLabel: string
empty: string
loading?: string
clearSelection: string
}
export interface ComboboxProps<T = string> {
options: readonly ComboboxOption<T>[]
messages: ComboboxMessages
id?: string
placeholder?: string
name?: string
form?: string
size?: ControlSize
disabled?: boolean
readonly?: boolean
required?: boolean
invalid?: boolean
clearable?: boolean
loading?: boolean
typoTolerant?: boolean
autocomplete?: 'none' | 'list'
by?: (a: T, b: T) => boolean
serialize?: (value: T) => string
}
// 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;
}