vue-auto-combo

vue-auto-combo

Live Storybook demo →

A fully-featured, dependency-free autocomplete / combo box component for Vue 3, built on raw HTML elements and the WAI-ARIA combobox pattern. The full behavioral requirements live in spec.md.

Features

• Autocomplete over a list of strings (case-insensitive substring matching, or bring your own filter)
• Single-select (v-model as string | null) and multi-select (string[])
• Chip-style display of multi-select values (or a plain text summary with chips: false)
• Strict mode (values must come from options) or free-text entry (freeText: true) with a create event
• Full keyboard support: arrows, Home/End, Enter, Escape, Tab, Backspace-to-remove-chip
• Accessible: combobox/listbox roles, aria-activedescendant, labelled chip remove buttons
• Client-side validation: rules functions, a validation event, and an exposed validate() method
• prefix / suffix slots for icons or icon buttons inside the control
• Loading spinner (loading) — a purely visual busy indicator inside the control
• Character counter (showCounter) with native maxlength enforcement
• Themeable via --ac-* CSS custom properties; zero runtime dependencies besides Vue

Usage

Installation

npm install vue-auto-combo

Or with pnpm:

pnpm add vue-auto-combo

Then import the component and its stylesheet:

<script setup>
import { ref } from 'vue'
import { AutoCombo } from 'vue-auto-combo'
import 'vue-auto-combo/style.css'

const fruit = ref(null)              // single-select
const tags = ref(['vue'])            // multi-select
</script>

<template>
  <AutoCombo v-model="fruit" :options="['Apple', 'Banana', 'Cherry']" label="Fruit" />
  <AutoCombo v-model="tags" :options="['vue', 'react', 'svelte']" multiple chips free-text />
</template>

Or register globally: app.use(VueAutoCombo) (default export).

Props

Events

update:modelValue, search, open, close, select, remove, create, validation ((valid: boolean, message: string | null), emitted on every validation run)

Slots

Exposed methods (template ref)

Styling

The component ships usable default styles in dist/vue-auto-combo.css (import it once: import 'vue-auto-combo/style.css'). Customize the look by targeting its classes from your own stylesheet.

The component's own <style> block is scoped, but scoping only affects selectors written inside that block — the class names are plain and stable, so a normal (non-scoped) stylesheet loaded after the component's CSS can target them directly.

Theming with CSS custom properties

The fastest way to reskin the component is to reassign its --ac-* custom properties on the .auto-combo class (or on a wrapper class around it). Custom properties inherit through the DOM, so setting them anywhere above the component in the tree works too.

Set these on the component (.auto-combo) as usual — when the dropdown teleports to <body>, its resolved --ac-* theme is forwarded onto the panel so it stays styled outside the component tree.

/* Theme every instance from a global stylesheet */
.auto-combo {
  --ac-bg: #262a36;
  --ac-text: #e7e9f0;
  --ac-border: #3a3f4f;
  --ac-border-focus: #8ea2ff;
  --ac-chip-bg: #333a52;
  --ac-chip-text: #c3cbff;
}

/* Or scope a theme to a subset of instances with an extra class */
.theme-dark.auto-combo {
  --ac-bg: #262a36;
  --ac-text: #e7e9f0;
}

<template>
  <AutoCombo v-model="fruit" :options="fruits" class="theme-dark" />
</template>

--ac-radius shapes both the control and the dropdown panel, so cranking it up to a pill value (e.g. 999px) ovals out the dropdown along with the input. For a true pill input, keep --ac-radius at a normal value and round just the control with a class override (see below) instead.

Class reference

For changes the custom properties don't cover — padding, shape, borders on individual parts — target the classes directly.

/* Example: square corners on chips, bolder active-option highlight */
.auto-combo .ac-chip {
  border-radius: 4px;
}

.auto-combo .ac-option--active {
  background: var(--ac-chip-text);
  color: #fff;
}

See the Styling page in Storybook for live, editable examples of both approaches.

Development

pnpm install
pnpm storybook   # interactive demos at http://localhost:6006
pnpm test        # Vitest component tests (one per spec requirement)
pnpm build       # library build (ESM + UMD + types) into dist/