Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Combobox

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.

Interactive showcase

Install

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

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.

Vue
<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.

When to use it

Large country list

Filter options by visible labels and alternate keywords.

Search and select

Control query text separately from the committed option value.

More examples

Country with aliases

Keywords help people find a value using another common name.

Country with aliases
<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>

Async project lookup

Type At, then quickly replace it with Be. Watch for Searching projects… in the list, then check that Beacon is the result.

Async project lookup
<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>

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.

Combobox

Complete API for Combobox
NameType or signatureDefaultWhat it does
optionspropreadonly ComboboxOption<T>[]RequiredChoices that a person can select.
messagespropComboboxMessagesRequiredSupply the text this component displays for its built-in actions and states.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
readonlypropboolean | undefinedNot setShow the value while preventing edits.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
clearablepropboolean | undefinedNot setShow an action for clearing the selected value.
loadingpropboolean | undefinedNot setShow that an action is in progress and prevent repeat activation.
typoTolerantpropboolean | undefinedtrueAllow 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) | 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.
modelValuemodelT | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
querymodelstring | 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) | undefinedOptionalContent for the option area of Combobox.
emptyslot(() => unknown) | undefinedOptionalContent for the empty area of Combobox.
loadingslot(() => unknown) | undefinedOptionalContent for the loading area of Combobox.
clearslot(() => unknown) | undefinedOptionalContent for the clear area of Combobox.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of Combobox.
inputexposedHTMLInputElement | 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.
Public type definitions
Public types
// 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;
}

Implementation notes

  • Object values use Object.is equality by default. Supply by for custom equality and serialize for meaningful object form values; objects without a serializer submit an empty value.
  • The model stores the option value, while v-model:query stores editable text.
  • Arrow navigation highlights an option; Enter commits it and Escape restores the selected label.

Accessibility and localization

  • Provide a field label and localize listbox, empty-state, and clear-action messages.

Source contract and editing guidance