Autocomplete — Forms

Autocomplete / Suggest

The suggest control adds type-ahead suggestions to any text input. Feed it a static JSON array or point it at a remote JSON endpoint — results filter as the user types, wired with useSuggest. Alias: data-vd-autocomplete.

Basic — Static JSON Array

Search Fruits

<input type="text"
  class="vd-input"
  placeholder="Type a fruit name…"
  data-vd-suggest='["Apple","Banana","Cherry","Grape","Mango","Orange","Peach","Strawberry"]'>

EU Capitals

Search EU Capitals

<input type="text"
  class="vd-input"
  placeholder="Type an EU capital…"
  data-vd-suggest='["Amsterdam","Athens","Berlin","Brussels","Dublin","Paris","Rome","Vienna"]'>

Minimum Characters (2)

Search EU Countries

<input type="text"
  class="vd-input"
  placeholder="Type at least 2 letters…"
  data-vd-suggest='["Austria","Belgium","France",…]'
  data-vd-suggest-min-chars="2">

Alias: `data-vd-autocomplete`

Search Colors

<!-- data-vd-autocomplete is an alias for data-vd-suggest -->
<input type="text"
  class="vd-input"
  data-vd-autocomplete='["Red","Orange","Yellow","Green","Blue"]'>

API Reference

Wiring

import { ref } from 'vue';
import { useSuggest } from "@vanduo-oss/vd3";

const root = ref<HTMLElement | null>(null);
useSuggest(root);   // wires [data-vd-suggest] inside root; cleanup on unmount

// react to a selection
root.value?.addEventListener('suggest:select', (e) => {
  console.log(e.detail.value);
});

CSS Classes

Class	Description
`.vd-suggest-wrapper`	Auto-generated wrapper around the input; positions the dropdown list
`.vd-suggest-list`	The dropdown `<ul>` containing suggestion items
`.vd-suggest-item`	Individual suggestion `<li>` inside the list
`.vd-suggest-match`	Wraps the matched substring within each suggestion item (bold highlight)
`.vd-suggest-empty`	Shown when no results match the current query

Data Attributes

Attribute	Description
`data-vd-suggest`	Activates the component. Optionally holds an inline JSON array of strings
`data-vd-suggest-url`	URL to fetch suggestions from a JSON endpoint. Overrides inline data
`data-vd-suggest-min-chars`	Minimum characters before the dropdown appears (default: 1)
`data-vd-autocomplete`	Alias for data-vd-suggest — works identically

Composable API

Symbol	Description
`useSuggest(root)`	Composable — attaches type-ahead suggestions to every [data-vd-suggest] / [data-vd-autocomplete] input inside the root ref. Call once in setup().
`(automatic cleanup)`	The dropdown, debounce timer and listeners are removed on component unmount.

Events

Event	Description
`suggest:select`	Fired on the input when the user picks a suggestion. event.detail contains the selected value string

Accessibility

The input receives role="combobox" and aria-autocomplete="list"
The suggestion list has role="listbox"; each item has role="option"
aria-expanded toggles true/false as the dropdown opens and closes
aria-activedescendant tracks the currently highlighted option for screen readers
↑ / ↓ arrow keys navigate the list; Enter selects; Escape closes
Focus returns to the input after selection, preserving natural tab order