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="…">.

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.