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" />
}gog-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.
Import the component and drop it into a template.
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> 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" />
} 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.
<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 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
/> 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"
/>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"
/>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]option.profile.role is checked under strictTemplates.
value: u1value: 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>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"
/>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" /> 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>[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 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>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>'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"
/>GOG_CONFIGcontrol.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>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>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>virtualizevirtualize 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.
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.
label, or ariaLabel; use inputId to wire your own <label for>. errorMessage sets aria-invalid="true" and an aria-describedby pointing at the message. aria-hidden, so the host carries aria-busy while loading is on. clearAriaLabel, or GOG_CONFIG.labels.clearSelection. | Name | Type | Default | Description |
|---|---|---|---|
openOnFocus | boolean | undefined | undefined | Whether 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. |
value | TValue | null | The selected value — whatever optionValue resolves to. Two-way bindable with [(value)]. |
filterLocal | boolean | true | Whether 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. |
minLength | number | GOG_CONFIG.autocomplete.minLength ?? 1 | How many characters before the panel opens at all. |
searchDebounce | number | GOG_CONFIG.autocomplete.searchDebounce ?? 300 | Milliseconds of quiet before gogSearch fires. 0 emits on every keystroke. |
loading | boolean | false | Shows a spinner in the trailing slot, for a server-backed source still fetching. |
emptyMessage | string | 'No matches' | Shown in place of the list when nothing matches. |
forceSelection | boolean | true | On, 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. |
inputId | string | '' | id for the inner <input>, for an external <label for="…">. |
ripple | boolean | undefined | undefined | Press 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. |
virtualize | boolean | undefined | GOG_CONFIG.dropdown.virtualize ?? false | Renders 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. |
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.
| Name | Type | Default | Description |
|---|---|---|---|
options | readonly TOption[] | [] | The suggestions. Your own objects. |
optionLabel | string | ((o: TOption) => string) | 'name' | Property path (dot-paths included) or function producing an option’s label. |
optionValue | string | ((o: TOption) => unknown) | null | 'id' | What the control emits. null emits the option object itself. |
optionDisabled | string | ((o: TOption) => boolean) | 'disabled' | Which suggestions cannot be picked. |
filterMatch | ((option: TOption, query: string) => boolean) | null | null | How filterLocal matches an option against the typed text. Left null, the resolved optionLabel is matched case-insensitively as a substring. |
label / placeholder / ariaLabel | string | '' / 'Select...' / '' | Field label, placeholder and accessible name. |
clearable / clearAriaLabel | boolean / string | GOG_CONFIG.control.clearable ?? false / 'Clear selection' | A clear button that appears only once there is something to clear. |
floatLabel / floatLabelShowPlaceholder | 'none' | 'in' | 'on' | 'over' / boolean | GOG_CONFIG.floatLabel.* ?? 'none' / false | Float-label variant and whether the placeholder reappears once it has floated. |
errorMessage / errorDisplay | string / 'manual' | 'auto' | '' / GOG_CONFIG.control.errorDisplay ?? 'manual' | Validation message, shown manually or derived from the bound form control. |
size / disabled / fullWidth / minWidth | GogSize / boolean / boolean / string | null | GOG_CONFIG.control.size ?? 'md' / false / true / null | Density, disabled state, and how the field sizes itself. |
appendToBody / dropdownDirection / dropdownWidth / dropdownMaxHeight / dropdownZIndex | boolean / GogDropdownDirection / string | null / string | null / number | null | GOG_CONFIG.dropdown.* ?? component defaults | Panel placement. appendToBody renders it into <body> so an overflow-clipped ancestor cannot cut it off. |
| Name | Payload | Description |
|---|---|---|
gogSearch | string | The current query, debounced. Wire a server-side lookup to this. |
gogLoadMore | void | The 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. |
valueChange | TValue | Emitted when the selection changes. Comes from the value model input. |
| Directive | Context | Description |
|---|---|---|
gogDropdownOption | $implicit, selected, disabled, label | Replaces one suggestion row. |
[gogDropdownOptionTypeOf] | readonly TOption[] — an input on gogDropdownOption | Bind 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. |
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.sizeGOG_CONFIG.control.errorDisplayGOG_CONFIG.control.clearableGOG_CONFIG.floatLabel.variantGOG_CONFIG.floatLabel.showPlaceholderGOG_CONFIG.dropdown.appendToBodyGOG_CONFIG.dropdown.directionGOG_CONFIG.dropdown.virtualizeGOG_CONFIG.ripple.enabledGOG_CONFIG.autocomplete.minLengthGOG_CONFIG.autocomplete.searchDebounceGOG_CONFIG.autocomplete.openOnFocusGOG_CONFIG.spinner.component — the spinner loading draws, which has no input of its ownGOG_CONFIG.spinner.variant — the same spinner, when no component is setGOG_CONFIG.labels.clearSelectionThis 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.
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.
| Token | Description |
|---|---|
--gog-autocomplete-label-color / -label-font-family / -label-font-size / -label-font-weight / -label-letter-spacing / -label-line-height / -label-text-transform | Field label. Each aliases its --gog-field-label-* counterpart. |
--gog-autocomplete-field-bg / -border-color / -text-color | Field surface, border and text. |
--gog-autocomplete-radius / -min-width | Field corner radius and the floor an auto-width field cannot collapse past. |
--gog-autocomplete-focus-ring-color / -focus-ring-width / -hover-border-color | Focus and hover states. |
--gog-autocomplete-panel-bg / -panel-border-color / -panel-shadow / -panel-max-height | Suggestion panel surface and height cap. |
--gog-autocomplete-option-hover-bg / -option-press-bg / -option-selected-bg | Suggestion row states. |
--gog-autocomplete-option-height / -panel-gap | A 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-size | The "nothing found" message and the loading spinner. |
--gog-autocomplete-clear-color / -clear-hover-color / -actions-inset | Clear button color and how far the trailing actions sit from the edge. |
--gog-autocomplete-float-label-reserve / -in-top / -over-gap / -over-reserve | Float-label geometry, derived from the shared --gog-field-float-label-* scale. |