Autocomplete

The widget is useful for two scenarios:

• The value for the textbox must be chosen from a predefined set of allowed values, e.g. a location field must contain a valid location name (a combo box).
• The textbox may contain any arbitrary value, but it is advantageous to suggest possible values, e.g. a search field (free solo).

Basic usage

Import AutocompleteComponent, pass an options array, map each option to its display string with getOptionLabel, and bind the selection with [(value)]. Options can be strings or objects; when an option object has a label property it is used automatically.

import { Component, signal } from '@angular/core';
import { AutocompleteComponent } from '@js-smart/ng-kit';

@Component({
	selector: 'app-demo',
	imports: [AutocompleteComponent],
	template: `
		<autocomplete [options]="films" [(value)]="value" label="Movie" placeholder="Pick a film" />
	`,
})
export class DemoComponent {
	protected readonly films = ['The Godfather', 'Pulp Fiction', 'Inception'];
	protected readonly value = signal<string | null>(null);
}

Combo box

The value must be chosen from a predefined set of allowed values. Selecting an option updates value; the Combo box and Country select examples show single-select over string and object option lists.

Controlled states

The component has two states that can be controlled independently: the value (the option the user has committed, via Enter or click) and the inputValue (the text shown in the box). They are deliberately independent, as in MUI — bind [(value)], [(inputValue)] and [(open)] to drive them from the outside (see the Controlled example).

Free solo

Set [freeSolo]="true" to allow arbitrary values in the textbox that are not bound to the options — ideal for a search box. Combine it with selectOnFocus, clearOnBlur and handleHomeEndKeys for a "creatable" experience that lets users add new values (see the Free solo example).

Grouped

Provide groupBy to group options under sticky headers; options must be sorted by the same grouping key. Customise the header markup by projecting a *ngGroupHeader template (see the Grouped example).

Disabled options

Use getOptionDisabled to prevent selection of specific options — useful for unavailable time slots or restricted choices.

Asynchronous requests

The component supports both "load on open" and "search as you type". For server-side filtering, pass a pass-through filterOptions (e.g. passThroughFilter) so the component does not filter again, and toggle loading to show loadingText while requests are in flight (see the Asynchronous requests example).

Multiple values

With [multiple]="true" the user can select several values, rendered as removable Material chips. Use filterSelectedOptions to hide already-selected options, and showCheckboxes for a checkbox listbox that stays open after each pick (see the Checkboxes example).

Fixed options

Pass fixedOptions to lock certain chips so they cannot be removed from the selection (see the Fixed tags example).

Limit tags

Use limitTags to cap the number of chips shown when the field is not focused; overflow is summarised as +N (customisable via getLimitTagsText).

Sizes & appearance

size switches between 'medium' and a denser 'small' field, and appearance chooses the Material form-field style ('fill' or 'outline'). See the Sizes & appearances example.

Custom rendering

Every slot is overridable via projected templates: *ngOption (MUI's renderOption, with a query for highlighting), *ngValue (renderValue), *ngGroupHeader (renderGroup), plus *ngPaper, *ngEmpty, *ngLoading, *ngPopupIcon and *ngClearIcon. The Custom rendering example shows query highlighting, custom icons and a custom paper surface.

Custom filter

Use createFilterOptions to tune the default matching: matchFrom ('any' | 'start'), stringify, trim, ignoreCase, ignoreAccents and limit. Pass the result to filterOptions. For fully custom (e.g. fuzzy) matching, provide your own filterOptions function.

Virtualization

Set [virtualize]="true" to render very large option lists efficiently with the CDK virtual scroll; tune itemSize and maxVisibleItems. The Virtualized example renders 10,000 options.

Events

Listen to valueChanged (with a reason: createOption, selectOption, removeOption, clear, blur), inputChanged, opened, closed and highlightChanged. Keyboard handling follows the WAI-ARIA combobox pattern.

Accessibility

The component implements the WAI-ARIA combobox pattern (role="combobox"/listbox/option, aria-activedescendant, full keyboard support). Always provide a label or ariaLabel for a compliant, labelled control.

API

Selectors

autocomplete, lib-autocomplete

Inputs

Outputs

Content template directives

Project a template to override a slot; each receives a typed context. These map to MUI's render props and slots.

Filter helpers

createFilterOptions(config?) builds a filterOptions function; defaultFilterOptions is the default, and passThroughFilter disables client-side filtering (for server-side search). Config options:

Per-element class/attribute overrides are available via slotProps (mirroring MUI's slotProps) for the root, input, listbox, paper, clearIndicator and popupIndicator slots. The headless NgAutocompleteState and all types are exported for advanced use.