GrAutocomplete

• there are too many options for a list — users, cities, tags, repositories: they are searched by typing, not browsed;
• the list comes from a server — source and debounce together with the “searching” and “nothing found” states;
• a minimum number of characters is needed — minQueryLength keeps the first letter from reaching the server;
• there are several values — multiple shows the selection as chips, each removable from the keyboard;
• the value may be missing from the reference list — allowCustomValue permits one of your own.

Two paths, mutually exclusive by meaning.

fetchOptions — the component runs the request:

<GrAutocomplete
  v-model="user"
  :fetch-options="fetchPeople"
  :min-query-length="1"
  @search-error="reportError"
/>

async function fetchPeople(query: string, signal: AbortSignal) {
  const response = await fetch(`/api/people?q=${query}`, { signal })
  return response.json()
}

Debouncing, cancelling the previous request and loading are on the component. The answer to a cancelled request is ignored: while typing quickly, the list always holds the result of the last request rather than of the one that came back later. Local filtering is switched off in this mode — the server filters the list. An error (other than a cancellation) leaves as a searchError event, and the list becomes empty.

search — the application runs the request:

<GrAutocomplete
  v-model="user"
  :options="options"
  :loading="pending"
  :filterable="false"
  @search="load"
/>

The path for those whose request lives in a store, a cache or a cancellation of its own. The race between answers is then settled by the application: the component only emits the debounced query and does not know which answer was brought to it.

allowCustomValue adds an “Add …” option to the list. It is an option like any other and takes part in arrow navigation: without that, committing a value of your own from the keyboard was impossible — with a non-empty list Enter always went to the active option.

The value is typed as text, so it is a string by nature: with a numeric TValue the branch does not apply.

The crosses on the chips are deliberately not tabbable: in a combobox the focus lives on the <input>, and twenty selected values must not produce twenty Tab stops. Navigation is by arrows: ← from an empty query moves to the last chip, ←/→ walk between them, Delete/Backspace removes one, and Esc, → from the last one and any printable character return to the field.

Backspace in an empty field still removes the last chip without entering navigation.

The direct children of role="listbox" are options only: the role declares everything else an invalid child. Loading, “type N more characters” and “nothing found” live below the list in a single live region role="status" aria-live="polite" — otherwise the asynchronous states would change silently.

The options do not take focus (mousedown is suppressed), so selecting with the mouse leaves the caret in the field — the panel does not reopen and the tab order is not disturbed.

virtual keeps in the DOM only the window around the viewport — the height of the window is set by dropdownMaxHeight. There is one scenario it is meant for: a remote search across a reference list with thousands of matches.

<GrAutocomplete v-model="city" :options="cities" virtual />

Three consequences worth knowing in advance.

The size of the set is declared explicitly. In the ordinary mode a screen reader derives it from the DOM, but with an incomplete set it would say “1 of 12” about a list of ten thousand. That is why with virtual the options carry aria-setsize and aria-posinset — for the whole filtered list, not for the window. In the ordinary mode those attributes are absent: there they would be noise.

The “Add …” row is a member of the set. With allowCustomValue it stands first and scrolls with the list rather than sticking to the top of the panel: the keyboard walks through it like through an ordinary option anyway.

The active option is always mounted. The arrows scroll the list to it before moving aria-activedescendant — otherwise the attribute would point at a node that is not in the DOM. How the primitive works and what it costs — virtual-list.md.

const box = useTemplateRef('box')
box.value?.focus()
box.value?.open()
box.value?.close()

disabled and readonly arrive both as props and from GrFormField. Both lock the control the same way: the panel does not open, options are not selected, chips are not removed, there is no clear button. The difference is only in semantics — readonly gives its value to the form and is announced as aria-readonly.

The slots put an icon, a unit or a label into the shell; the width is bounded by six props (prefixMinWidth/prefixMaxWidth/prefixFixed and the same for the suffix). The shared contract of the controls — form-controls.md.

The panel is controllable through v-model:open (the shared contract of panel overlays, as in GrPopover): without the open prop the previous uncontrolled behaviour holds, with it the parent owns the state and update:open accompanies every change.

The name prop enables participation in a native form: hidden inputs serialise the value of the model, not the text of the query — one per value with multiple, nothing when the selection is empty.

While the query is shorter than minQueryLength, the panel shows the “type N more characters” hint rather than the results of the previous query — a stale list below the hint would misinform. With allowCustomValue the hint stands next to the “Add …” row: that row explains what to do with what has been typed, but not where the options went.

In remote mode (fetchOptions) the options prop is the starting list until the first answer from the server. Replacing it in the parent makes it the source again until the next answer and cancels the request in flight: that one belongs to the previous data set. The change is tracked by content, not by the identity of the array, so an inline literal :options="[...]" is safe — a list recreated on re-render with the same options does not touch the remote results.