Typeahead, one file.

API reference

Constructor & usage

Bind to any <input> by CSS selector or element. Binding an element that already has an instance destroys the old one first; a target that can't be found throws. Without a DOM (SSR) the constructor returns an inert instance whose methods all no-op.

var ac = new Autocomplete('#q', { source: ['Apple', 'Apricot'] })

Autocomplete.create('#q', {...})   // constructor alias, same signature
Autocomplete.get('#q')             // instance already bound to that element, or null
Autocomplete.autoInit(root?)       // init every [data-vac] under root (default: document)

The source option accepts three shapes — results may be plain strings or item objects (see Options):

// 1. Array — filtered locally (case/diacritic-insensitive substring on label)
source: ['Alpha', 'Beta', { value: 'g', label: 'Gamma' }]

// 2. Callback — call done(results) whenever you're ready
source: function (query, done) {
  fetch('/api?q=' + encodeURIComponent(query))
    .then(r => r.json()).then(done)
}

// 3. Promise — return a thenable that resolves to results
source: query => fetch('/api?q=' + encodeURIComponent(query)).then(r => r.json())

Every lookup carries a sequence token: results arriving for a superseded query are discarded, so a slow response can never overwrite the current list. A rejected promise or thrown source closes the panel silently and calls onError. If a function source both calls done() and returns a promise, whichever settles first wins.

Options

All keys of Autocomplete.defaults, with their exact defaults from the source. Mutate Autocomplete.defaults to change them globally; per-instance options win over defaults.

labels.*

There are no per-call-only options beyond the defaults keys above.

Item shape

Source results may be plain strings (shorthand for value = label = the string) or objects. A missing value falls back to label and vice versa; both are coerced to strings.

Instance methods

Readable instance properties: input (the bound element), opts (resolved options), isOpen (boolean), and items (the last delivered, normalized results).

Statics & helpers

Events & callbacks

Option callbacks receive the instance as their last argument:

The component also dispatches bubbling CustomEvents on the bound input, so you can listen without a reference to the instance:

document.getElementById('q').addEventListener('autocomplete:select', function (e) {
  console.log(e.detail.item.value)
})

All three bubble (bubbles: true). No native input or change events are dispatched programmatically — when a selection fills the input (or allowNew: false reverts it), the value is written directly.

Declarative init

Add data-vac to an input and it is picked up automatically on DOMContentLoaded (or immediately if the script loads later); call Autocomplete.autoInit(root) yourself for content added after that. Already-bound elements are skipped.

<input data-vac data-vac-source='["Apple","Apricot","Banana"]' data-vac-min-chars="2">

The component itself sets data-vac-bound on the input while an instance is attached; it is removed on destroy().

Theming

With theme: 'auto' (the default) the panel resolves its theme in the family's order — <html data-theme> / data-bs-theme → .dark / .light class on <html> → prefers-color-scheme — and re-resolves live when any of those change (via the shared VC engine when the core is loaded, otherwise a private watcher). Pin per instance with theme: 'light' or 'dark'. Every color is a CSS custom property on .vac (dark values on .vac[data-theme=dark]):

.vac { --vac-accent: #b45309; }   /* per page — no core needed */
VC.config({ accent: '#b45309' })  /* with the VC core: themes the whole family */

CSS isolation: the panel renders as class="vac vac-panel vc1" and every structural rule ships salted (.vac.vc1 .vac-option { … }) so host-page design systems can't override it, while the --vac-* variable definitions stay deliberately unsalted so page overrides keep working. Set Autocomplete.salt = 'acme' for a custom token or Autocomplete.salt = false to disable — before the first instance. The host <input> itself is never styled.

Headless: pass styles: false (or set Autocomplete.defaults.styles = false) and no CSS is ever injected; you keep the full behavior — async guards, keyboard, ARIA — and style the markup contract below yourself. The stock stylesheet is available as the Autocomplete.css string as a starting point.

input[data-vac-bound]                 ← your input, untouched
.vac.vac-panel[data-theme="dark"]     ← .vac-open while visible;
  .vac-list[role="listbox"]             is-loading / is-empty state classes
    [role="group"] > .vac-group-label ← only when items carry `group`
    .vac-option.is-active             ← .vac-match wraps the matched substring
  .vac-loading                        ← spinner row while a lookup is in flight
  .vac-empty                          ← shown when query ≥ minChars, no results

Accessibility

The bound input becomes the combobox: it gets role="combobox", aria-autocomplete="list", aria-expanded, aria-controls (pointing at the list) and autocomplete="off"; original attribute values are restored on destroy(). The panel's list is role="listbox" (labelled by labels.suggestions) with role="option" rows carrying aria-selected and, when disabled, aria-disabled="true"; grouped items sit inside role="group" containers labelled with the group name. Browsing moves aria-activedescendant on the input only — the typed text is never changed until a commit. Reduced motion is respected (prefers-reduced-motion disables all transitions).

Blur closes the panel; with allowNew: false it also reverts unmatched text first. Home and End are not intercepted — they keep their native caret behavior in the input.