GUILD OF GLEKS UIv21.19.0

gog-autocomplete

Autocomplete

A text field that suggests options as you type. It shares GogDropdownBase with Select — the same option accessors, placement, float label, error state and ControlValueAccessor — but its trigger is a real <input>, which is what makes it a separate control rather than a mode of the select.

Overview

Import the component and drop it into a template.

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

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

Basic usage — type a letter or two. [(value)] holds the picked option's id:

value: null
<div>
  <gog-autocomplete label="City" placeholder="Start typing…" [options]="cities" [(value)]="city" />
  <code>value: {{ city() ?? 'null' }}</code>
</div>

Examples

Sizes

Five steps, also settable app-wide through GOG_CONFIG.control.size.

@for (size of sizes; track size) {
  <gog-autocomplete [size]="size" [label]="size" [options]="cities" [value]="4" />
}

States

Empty with a placeholder, holding a value, disabled, with an error, and loading — [loading] puts a spinner in the trailing slot for a source that is still fetching. There is no chevron: the trigger is a text field, not a button, so nothing claims it is a list you open by clicking.

Pick a city
<gog-autocomplete label="Value unset" placeholder="Search cities" [options]="cities" />
<gog-autocomplete label="Value set" [options]="cities" [value]="4" />
<gog-autocomplete label="Disabled" [options]="cities" [value]="4" disabled />
<gog-autocomplete label="Error" [options]="cities" errorMessage="Pick a city" />
<!-- A spinner in the trailing slot while a source is still fetching. -->
<gog-autocomplete label="Loading" [options]="cities" loading />

Clearable

clearable is opt-in, and it watches the text, not the selection: type two letters into the third field and the clear button appears before anything is picked, because on this control the two can disagree. Clearing empties both and emits gogSearch with an empty query, so a server-backed list resets with it. The spinner shares the trailing slot, and the field makes room for both.

<gog-autocomplete label="Berlin selected" [options]="cities" clearable [value]="4" />
<gog-autocomplete label="Clearable and loading" [options]="cities" clearable loading [value]="4" />
<!-- Type two letters: the clear button watches the text, not the selection. -->
<gog-autocomplete
  label="Nothing selected"
  placeholder="Type two letters"
  [options]="cities"
  clearable
/>

Width

A field fills its container by default — the dashed box here. Unlike the two listbox controls, the trigger does not size to its content: it is an <input>, whose own width is the browser's default, so [fullWidth]="false" gives you that box and minWidth is the floor under it.

<gog-autocomplete label="fullWidth (default)" [options]="cities" [value]="4" />
<gog-autocomplete label='[fullWidth]="false"' [fullWidth]="false" [options]="cities" [value]="4" />
<gog-autocomplete
  label='[fullWidth]="false" minWidth="22rem"'
  [fullWidth]="false"
  minWidth="22rem"
  [options]="cities"
/>

No visible label

ariaLabel names a field that has no label. With neither, the placeholder is the fallback accessible name — better than nothing, but it disappears the moment anything is typed.

<gog-autocomplete
  ariaLabel="City (no visible label)"
  placeholder="Search cities"
  [options]="cities"
/>

Your own objects

optionLabel, optionValue and optionDisabled take a property path — dot-paths included — or a function, so a real DTO goes in unmapped. [optionValue]="null" hands back the option object itself. A gogDropdownOption template replaces one row, with the option plus selected, disabled and the resolved label in its context; [gogDropdownOptionTypeOf]21.15.0 types the option, so option.profile.role is checked under strictTemplates.

value: u1
value: null
<!-- Property paths, dot-paths included: a DTO goes in unmapped. -->
<div>
  <gog-autocomplete
    label="Reviewer (by uuid)"
    placeholder="Search people"
    [options]="members"
    optionLabel="profile.fullName"
    optionValue="uuid"
    optionDisabled="suspended"
    [(value)]="memberId"
  />
  <code>value: {{ memberId() ?? 'null' }}</code>
</div>

<!-- A function label, and [optionValue]="null": the value is the option object itself. -->
<div>
  <gog-autocomplete
    label="Reviewer (whole object)"
    placeholder="Search people"
    [options]="members"
    [optionLabel]="fullName"
    [optionValue]="null"
    [(value)]="member"
  >
    <!-- [gogDropdownOptionTypeOf] types `option` as a Member. -->
    <ng-template gogDropdownOption [gogDropdownOptionTypeOf]="members" let-option let-label="label">
      {{ label }} — <em>{{ option.profile.role }}</em>
    </ng-template>
  </gog-autocomplete>
  <code>value: {{ member()?.uuid ?? 'null' }}</code>
</div>

A disabled option, and the empty message

optionDisabled defaults to the disabled property, so an option carrying it needs no binding: the row stays in the list, reports aria-disabled, and neither the pointer nor Enter picks it. emptyMessage replaces the list when nothing matches — type zz into the second field.

<!-- optionDisabled reads `disabled` off each option by default. -->
<gog-autocomplete label="Plan" placeholder="Search plans" [options]="plans" />
<gog-autocomplete
  label="Empty message"
  placeholder="Try zz"
  [options]="cities"
  emptyMessage="No city by that name"
/>

Local filtering — filterMatch

Local filtering matches the query as a case-insensitive substring of the resolved label. filterMatch swaps in any predicate: type b into both — the default keeps Dublin, Lisbon and Zagreb beside the five cities that start with B; the prefix matcher keeps only those five.

<gog-autocomplete label="Default (substring)" [options]="cities" />
<gog-autocomplete label="startsWith" [options]="cities" [filterMatch]="startsWith" />

Two-way binding, and the text that is not the value

The field holds two things: what is typed, and what is committed. Pick Berlin, then edit the text — the value stays Berlin until the edit resolves, and Esc or clicking away snaps the text back. That is forceSelection, on by default: a user who types one more character to refine a search does not silently lose what they had picked.

value: null · 0 valueChange
<div>
  <gog-autocomplete
    label="City"
    placeholder="Search cities"
    [options]="cities"
    clearable
    [(value)]="city"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <code>value: {{ city() ?? 'null' }} · {{ changes() }} valueChange</code>
</div>

Free text — [forceSelection]="false"

For a create-as-you-type flow, where the text itself is the answer. Neither blur nor Esc touches what was typed — Esc only closes the panel 21.15.0 — and value is dropped as soon as the text stops matching, so the two never disagree. Read the text from gogSearch, not from value.

gogSearch: "" · 0 valueChange
<!-- forceSelection off: the text itself is the answer; read it from gogSearch. -->
<div>
  <gog-autocomplete
    label="Tag"
    placeholder="Pick one or invent one"
    [options]="cities"
    [forceSelection]="false"
    (gogSearch)="draft.set($event)"
    (valueChange)="changes.update((n) => n + 1)"
  />
  <code>gogSearch: "{{ draft() }}" · {{ changes() }} valueChange</code>
</div>

Reactive forms

errorDisplay="auto" shows the error once the control is touched and invalid: focus the field and leave it without picking. Text that matches no option leaves the value null, so a required field stays invalid however full the box looks — the point of forceSelection being on.

value: null · touched: false · disabled: false
<div>
  <gog-autocomplete
    label="City (reactive form)"
    placeholder="Search cities"
    [options]="cities"
    [formControl]="control"
    errorMessage="Pick a city from the list"
    errorDisplay="auto"
  />
  <div>
    <gog-button variant="outline" size="sm" (gogClick)="control.markAsTouched()">
      markAsTouched()
    </gog-button>
    <gog-button variant="outline" size="sm" (gogClick)="toggleDisabled()">
      {{ control.disabled ? 'enable()' : 'disable()' }}
    </gog-button>
  </div>
  <code>
    value: {{ control.value ?? 'null' }} · touched: {{ control.touched }} · disabled:
    {{ control.disabled }}
  </code>
</div>

Float label

'none' keeps the label above the field; 'in', 'on' and 'over' rest it inside until focus or a value moves it clear — each shown empty, then holding a value. floatLabelShowPlaceholder brings the placeholder back once the label has floated.

@for (variant of variants; track variant) {
  <gog-autocomplete
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    placeholder="e.g. Berlin"
    [options]="cities"
  />
  <gog-autocomplete
    [floatLabel]="variant"
    [label]="'floatLabel: ' + variant"
    [options]="cities"
    [value]="4"
  />
}

<!-- The placeholder shows under the floated label once it has somewhere to float to. -->
<gog-autocomplete
  floatLabel="over"
  floatLabelShowPlaceholder
  label="floatLabelShowPlaceholder"
  placeholder="e.g. Berlin"
  [options]="cities"
/>

App-wide defaults — GOG_CONFIG

control.size and the autocomplete keys set the defaults for every field under the provider; an instance's own input still wins. Here the second field opens only after two letters, and the third reports one query a second. In an app the provider goes in app.config.ts — see Global Configuration.

0 gogSearch
<gog-autocomplete label="Size from the config (lg)" [options]="cities" />
<gog-autocomplete label="Focus, then type two letters" [options]="cities" />
<div>
  <gog-autocomplete
    label="One query a second"
    [options]="cities"
    (gogSearch)="searches.update((n) => n + 1)"
  />
  <code>{{ searches() }} gogSearch</code>
</div>

Searching, and a server behind it

openOnFocus — on by default — opens the panel with the whole list the moment the field is focused, before minLength would have let anything through; for a short, known list that is the difference between a combobox and a text field the user has to guess at. Off, nothing opens until enough has been typed. Focus each field without typing, then type one letter:

<gog-autocomplete label="Default: opens on focus" [options]="cities" />
<gog-autocomplete label='[openOnFocus]="false"' [options]="cities" [openOnFocus]="false" />
<gog-autocomplete
  label='[minLength]="3", no openOnFocus'
  placeholder="Three letters"
  [options]="cities"
  [minLength]="3"
  [openOnFocus]="false"
/>

gogSearch is debounced — searchDebounce, 300 ms by default — so a lookup fires once the typing settles. Type a word at speed into each and compare the counters: 0 emits on every keystroke, which a local source can afford and a server-backed one cannot.

0 gogSearch · last: ""
0 gogSearch · last: ""
<div>
  <gog-autocomplete
    label="Default (300 ms)"
    [options]="cities"
    (gogSearch)="record('slow', $event)"
  />
  <code>{{ searches().slow }} gogSearch · last: "{{ last().slow }}"</code>
</div>
<div>
  <gog-autocomplete
    label='[searchDebounce]="0"'
    [options]="cities"
    [searchDebounce]="0"
    (gogSearch)="record('eager', $event)"
  />
  <code>{{ searches().eager }} gogSearch · last: "{{ last().eager }}"</code>
</div>

A server-backed field is three inputs: (gogSearch) runs the lookup, [loading] shows it is running, and [filterLocal]="false" stops the answer being filtered a second time. That last one is the bug worth naming: the server matched on fields this component cannot see, so filtering its reply against the same query silently drops rows. This lookup also matches the country — type germany.

last query: "" · 0 result(s)
<div>
  <gog-autocomplete
    label="City"
    placeholder="Type at least 2 characters"
    [options]="results()"
    [filterLocal]="false"
    [loading]="loading()"
    [minLength]="2"
    clearable
    (gogSearch)="search($event)"
  />
  <code>last query: "{{ query() }}" · {{ results().length }} result(s)</code>
</div>

gogLoadMore fires when the panel is scrolled to its end — the signal to fetch and append the next page rather than handing every row over up front. Open the panel and scroll to the bottom:

loaded: 20 / 200
<div>
  <gog-autocomplete
    label="Contact"
    placeholder="Scroll to load more"
    [options]="contacts()"
    [loading]="loading()"
    (gogLoadMore)="loadMore()"
  />
  <code>loaded: {{ contacts().length }} / {{ total }}</code>
</div>

The panel — appendToBody

The panel renders inline by default and is clipped by any scrolling or overflow: hidden ancestor. appendToBody moves it into <body> and positions it against the trigger. Type in the first two: only the appended one survives its box. dropdownWidth and dropdownMaxHeight take any CSS length and apply only while the panel is appended — an inline panel matches the trigger.

<!-- The box clips its content, as an overflow: hidden card or a scroller does. -->
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
  <gog-autocomplete label="Inline panel (clipped)" [options]="cities" dropdownDirection="down" />
</div>
<div style="overflow: hidden; padding: 12px; border: 1px dashed var(--gog-border-color)">
  <gog-autocomplete
    label="appendToBody (escapes)"
    [options]="cities"
    dropdownDirection="down"
    appendToBody
  />
</div>
<div>
  <gog-autocomplete
    label="Panel 240px wide, 160px tall"
    [options]="cities"
    appendToBody
    dropdownWidth="240px"
    dropdownMaxHeight="160px"
  />
</div>

Virtualized options — virtualize

virtualize renders only the rows in view. Both fields hold the same 10 000 options: unwindowed, that is 10 000 DOM rows to show about six — measured in Chrome, 512 ms before the panel appears, against 21 ms windowed. The scrollbar looks the same either way, because spacers stand in for the rows that are not there.

<gog-autocomplete label="virtualize" placeholder="Search cities" [options]="cities" virtualize />
<gog-autocomplete label="Eager (default)" placeholder="Search cities" [options]="cities" />

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 one. Set it per field, or app-wide with GOG_CONFIG.dropdown.virtualize. aria-setsize and aria-posinset keep the announced count real, and the arrows walk the whole list — End reaches the last option. Focus never moves, which is how this differs from the select: a combobox keeps focus in its input. gogLoadMore is not a substitute and the two compose — that one keeps the records the server sends small, this one the rows the browser builds.

Accessibility

The trigger is a real <input role="combobox">. DOM focus never leaves it: the highlighted row is pointed at with aria-activedescendant rather than being focused, which is what makes this a combobox rather than a select, and why typing keeps working while the panel is open. The rows are role="option" and are never tab stops.

  • Keyboard — the arrows highlight, Home/End jump to the ends, Enter picks the highlighted row (and does nothing when there is none), Esc closes the panel, Tab closes and moves on.
  • Name — label, or ariaLabel; use inputId to wire your own <label for>.
  • Error — errorMessage sets aria-invalid="true" and an aria-describedby pointing at the message.
  • Loading — the spinner is aria-hidden, so the host carries aria-busy while loading is on.
  • Clear button — named by clearAriaLabel, or GOG_CONFIG.labels.clearSelection.

API Reference

Inputs — autocomplete's own

NameTypeDefaultDescription
openOnFocusboolean | undefinedundefinedWhether focusing the field opens the panel immediately with the full option list, rather than waiting for minLength characters. Unset, falls back to GOG_CONFIG.autocomplete.openOnFocus, then to true.
valueTValuenullThe selected value — whatever optionValue resolves to. Two-way bindable with [(value)].
filterLocalbooleantrueWhether options are narrowed in the browser as you type. Turn it OFF when gogSearch fetches an already-filtered list: filtering that answer a second time is the classic double-filtering bug, and it silently drops rows the server matched on a field this component cannot see.
minLengthnumberGOG_CONFIG.autocomplete.minLength ?? 1How many characters before the panel opens at all.
searchDebouncenumberGOG_CONFIG.autocomplete.searchDebounce ?? 300Milliseconds of quiet before gogSearch fires. 0 emits on every keystroke.
loadingbooleanfalseShows a spinner in the trailing slot, for a server-backed source still fetching.
emptyMessagestring'No matches'Shown in place of the list when nothing matches.
forceSelectionbooleantrueOn, the field always ends up reflecting a real selection — editing is transient and Escape or blur snaps the text back. Off, the typed text is itself meaningful (a create-as-you-type flow): it is left alone by blur and by Escape, which only closes the panel, and value is dropped as soon as it stops matching, so the two never disagree.
inputIdstring''id for the inner <input>, for an external <label for="…">.
rippleboolean | undefinedundefinedPress ripple on each option row in the panel. Unset, falls back to GOG_CONFIG.ripple.enabled, which is off by default; setting it here wins over the app-wide value in both directions.
virtualizeboolean | undefinedGOG_CONFIG.dropdown.virtualize ?? falseRenders only the suggestion rows in view — about twenty in the DOM whatever the list holds. Off by default and never switched on at a row count: Ctrl+F finds only rendered rows and :last-child matches the last rendered one. aria-setsize/aria-posinset keep the announced count real.

Inputs — shared with Select

These come from GogDropdownBase and behave as they do on Select. The panel's search box is not among them: an autocomplete's trigger already is the search box, so filter, filterPlaceholder, filterPosition and filterEmptyMessage do not exist here — they did until 21.16.0, deprecated and doing nothing, and binding one is now a compile error. Use placeholder and emptyMessage. filterMatch still applies, since it plugs into filterLocal's own matching.

NameTypeDefaultDescription
optionsreadonly TOption[][]The suggestions. Your own objects.
optionLabelstring | ((o: TOption) => string)'name'Property path (dot-paths included) or function producing an option’s label.
optionValuestring | ((o: TOption) => unknown) | null'id'What the control emits. null emits the option object itself.
optionDisabledstring | ((o: TOption) => boolean)'disabled'Which suggestions cannot be picked.
filterMatch((option: TOption, query: string) => boolean) | nullnullHow filterLocal matches an option against the typed text. Left null, the resolved optionLabel is matched case-insensitively as a substring.
label / placeholder / ariaLabelstring'' / 'Select...' / ''Field label, placeholder and accessible name.
clearable / clearAriaLabelboolean / stringGOG_CONFIG.control.clearable ?? false / 'Clear selection'A clear button that appears only once there is something to clear.
floatLabel / floatLabelShowPlaceholder'none' | 'in' | 'on' | 'over' / booleanGOG_CONFIG.floatLabel.* ?? 'none' / falseFloat-label variant and whether the placeholder reappears once it has floated.
errorMessage / errorDisplaystring / 'manual' | 'auto''' / GOG_CONFIG.control.errorDisplay ?? 'manual'Validation message, shown manually or derived from the bound form control.
size / disabled / fullWidth / minWidthGogSize / boolean / boolean / string | nullGOG_CONFIG.control.size ?? 'md' / false / true / nullDensity, disabled state, and how the field sizes itself.
appendToBody / dropdownDirection / dropdownWidth / dropdownMaxHeight / dropdownZIndexboolean / GogDropdownDirection / string | null / string | null / number | nullGOG_CONFIG.dropdown.* ?? component defaultsPanel placement. appendToBody renders it into <body> so an overflow-clipped ancestor cannot cut it off.

Outputs

NamePayloadDescription
gogSearchstringThe current query, debounced. Wire a server-side lookup to this.
gogLoadMorevoidThe panel was scrolled to the end. Fetch the next page and append it to options — this is how a large or server-backed option source is paged without a virtual scroller.
valueChangeTValueEmitted when the selection changes. Comes from the value model input.

Content slots

DirectiveContextDescription
gogDropdownOption$implicit, selected, disabled, labelReplaces one suggestion row.
[gogDropdownOptionTypeOf]21.15.0readonly TOption[] — an input on gogDropdownOptionBind the same array as options and $implicit is typed as its element instead of unknown. Never read at runtime; left unbound, the template compiles exactly as before.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.control.size
  • GOG_CONFIG.control.errorDisplay
  • GOG_CONFIG.control.clearable
  • GOG_CONFIG.floatLabel.variant
  • GOG_CONFIG.floatLabel.showPlaceholder
  • GOG_CONFIG.dropdown.appendToBody
  • GOG_CONFIG.dropdown.direction
  • GOG_CONFIG.dropdown.virtualize
  • GOG_CONFIG.ripple.enabled
  • GOG_CONFIG.autocomplete.minLength
  • GOG_CONFIG.autocomplete.searchDebounce
  • GOG_CONFIG.autocomplete.openOnFocus
  • GOG_CONFIG.spinner.component — the spinner loading draws, which has no input of its own
  • GOG_CONFIG.spinner.variant — the same spinner, when no component is set
  • GOG_CONFIG.labels.clearSelection

This site is not on the default here. The library ships ripple.enabled as false; these docs set it to true app-wide so the demos above actually show the press feedback. In a fresh app you get no ripple until you ask for one — the droplet button in the header switches this site between the two, and it is on right now.

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.

TokenDescription
--gog-autocomplete-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transformField label. Each aliases its --gog-field-label-* counterpart.
--gog-autocomplete-field-bg / -border-color / -text-colorField surface, border and text.
--gog-autocomplete-radius / -min-widthField corner radius and the floor an auto-width field cannot collapse past.
--gog-autocomplete-focus-ring-color / -focus-ring-width / -hover-border-colorFocus and hover states.
--gog-autocomplete-panel-bg / -panel-border-color / -panel-shadow / -panel-max-heightSuggestion panel surface and height cap.
--gog-autocomplete-option-hover-bg / -option-press-bg / -option-selected-bgSuggestion row states.
--gog-autocomplete-option-height / -panel-gapA seed for the first frame rather than the row height — the component measures a real row and corrects itself, which is also what places the panel above or below the field. And the gap between the field and its panel.
--gog-autocomplete-empty-color / -spinner-sizeThe "nothing found" message and the loading spinner.
--gog-autocomplete-clear-color / -clear-hover-color / -actions-insetClear button color and how far the trailing actions sit from the edge.
--gog-autocomplete-float-label-reserve / -in-top / -over-gap / -over-reserveFloat-label geometry, derived from the shared --gog-field-float-label-* scale.