Autocomplete

Overview

Import the component and drop it into a template.

import { AutocompleteComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [AutocompleteComponent],
})

Basic usage — type a letter or two:

<gog-autocomplete
  label="City"
  placeholder="Start typing…"
  [options]="cities"
  [(value)]="city"
/>

Server-backed suggestions

Two things shape how the panel behaves before a query even runs. openOnFocus21.3.1 — on by default — opens the panel with the full option list the moment the field is focused, instead of waiting for minLength characters: for a short, known list that is the difference between a combobox and a text field the user has to guess at. Turn it off per instance, or app-wide with GOG_CONFIG.autocomplete.openOnFocus, to keep the older behaviour of showing nothing until something is typed.

gogLoadMore21.3.1 fires when the panel is scrolled to its end. Fetch the next page and append it to options — that is how a large or server-backed source is paged, with no virtual scroller involved.

gogSearch is debounced (searchDebounce, 300 ms by default), so a lookup fires once the typing settles rather than on every keystroke. Set [filterLocal]="false" alongside it: the server has already filtered, and filtering its answer a second time against the same query is the classic double-filtering bug — it silently drops rows the server matched on a field this component cannot see.

<gog-autocomplete
  label="City"
  [options]="results()"
  [loading]="loading()"
  [filterLocal]="false"
  [searchDebounce]="300"
  [minLength]="2"
  (gogSearch)="search($event)"
  [(value)]="city"
/>

Examples

<!-- optionValue="null" hands back the option object itself, not an id. -->
<gog-autocomplete
  label="City"
  optionLabel="name"
  [optionValue]="null"
  [options]="cities"
  [(value)]="cityObject"
/>

<gog-autocomplete label="City" [options]="cities" [(value)]="slotCity">
  <ng-template gogDropdownOption let-option let-label="label">
    <strong>{{ label }}</strong>
    <small>{{ option.country }}</small>
  </ng-template>
</gog-autocomplete>

<!-- forceSelection="false": what was typed is itself meaningful. -->
<gog-autocomplete
  label="Tag"
  [forceSelection]="false"
  [options]="cities"
  (gogSearch)="draft.set($event)"
  [(value)]="freeText"
/>

Accessibility

The <input> keeps DOM focus the whole time and the highlighted suggestion is pointed at with aria-activedescendant — where a listbox would move focus onto the option itself. That is the difference that makes this a combobox rather than a select, and it is why typing keeps working while the panel is open.

Arrow keys move the highlight, Enter picks it, Escape closes the panel. Give the field a label or an ariaLabel; use inputId if you are wiring your own <label for="…">.

Virtualized options — virtualize21.13.0

[virtualize]="true" renders only the rows in view. Unwindowed, 10 000 options build 10 000 DOM rows to show about six — measured in Chrome, 512 ms before the panel appears, against 21 ms windowed on the same data. The scrollbar looks the same either way, because spacers stand in for the rows that are not there.

<gog-autocomplete label="City" [options]="cities" [virtualize]="true" />

Off by default, and never switched on at some row count. A windowed list behaves differently in ways nothing about the data predicts: Ctrl+F finds only the rendered rows, and CSS targeting :last-child matches the last rendered row. A threshold would make that depend on how much data happened to arrive, so set it per field, or app-wide with GOG_CONFIG.dropdown.virtualize.

• The announced count stays honest: the aria-setsize and aria-posinset carry the real list, so a screen reader hears "10 000 items" rather than "20". Arrow keys walk the whole list — End reaches the last option.
• Focus never moves, which is the one way this differs from the select and the multiselect. Their windowed lists hand focus back to the trigger when a focused row scrolls away; a combobox keeps focus in its input the whole time, so there is nothing to hand back.
• gog-table's virtualize is a different story under the same name: table rows vary in height, so it measures as it goes — see the Table page.

Not the same thing as gogLoadMore, and the two compose. The server-backed suggestions above keep the number of records the server sends small; virtualize keeps the number of rows the browser builds small. A gogLoadMore list that has loaded 10 000 records still stamps 10 000 rows without it — neither implies the other, and a list long enough to want one usually wants both.

API Reference

Inputs — autocomplete's own

Inputs — shared with Select

These come from GogDropdownBase and behave exactly as they do on Select. The one exception is filter: an autocomplete's trigger already is the search box, so the panel never gets a second one — filterMatch still applies, though, since it plugs into filterLocal's own matching rather than the panel's search box.

Outputs

Content slots

Styling Tokens

Every CSS custom property the autocomplete paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.