GrAutocomplete

<GrAutocomplete
  v-model="city"
  :options="[
    { label: 'Europe', options: [{ value: 'lis', label: 'Lisbon' }] },
    { label: 'Asia', options: [{ value: 'tyo', label: 'Tokyo' }] },
    { value: 'remote', label: 'Remote' },
  ]"
/>

The shape of the data is the same as in GrSelect: two neighbouring controls whose lists differ only in the way of input are obliged to accept data the same way. Groups and single options mix in one array.

The filter hides a group as a whole if nothing in it matched. A heading over emptiness reads as a failure rather than as “there is nothing here”.

The keyboard walks the options only. The heading of a group is not selected with the arrows and does not enter the set for the screen reader: the direct children of role="listbox" are obliged to be options, so the heading lies inside its group and gives it a name through aria-labelledby. With virtualisation the window may start below the heading — then the name of the group goes into aria-label, and the group stays named all the same.

The same value in different groups is not an error: the key of a row is assembled with the index of the group, so two such options do not collapse into a single node, and hovering with the mouse highlights the one that is hovered.

Groups come from the server as well: fetchOptions is entitled to return the same array with groups, and the signature of the set is computed from their content — a change of an option inside a group does not go unnoticed.

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.

dropdownMaxHeight is the ceiling of the list, not of the panel. The panel itself is bounded by the room left to the edge of the viewport: the layer reports the measurement in --gr-floating-available-height, and on a short screen it is the list that shrinks — the input field and the status row stay in view, and there is a single scrollbar. The mechanism is shared across the list panels of the package and is described in ../overlays.md.

virtual keeps in the DOM only the window around the viewport — its height is set by dropdownMaxHeight or by the available room, if there is less of it. 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.

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.