@ngui/auto-complete

A versatile Angular autocomplete library that works as both a directive (attached to any input) and a standalone component.

Live Demo

Installation

npm install @ngui/auto-complete @angular/cdk

The directive positions its dropdown with the CDK Overlay, so @angular/cdk is a peer dependency and your app must include the CDK overlay styles once:

/* styles.scss — skip this if you already import an Angular Material theme (it bundles them) */
@import '@angular/cdk/overlay-prebuilt.css';

Styling the dropdown: because the directive renders its dropdown in an overlay at the document root, any custom dropdown styles (e.g. classes used by a list-formatter or template) must be global, not scoped to an ancestor of the input. See Theming to restyle it with CSS variables.

Setup

Standalone (Angular 21+)

The component and directive are standalone. Import them directly into your standalone component (or NgModule) imports:

import { NguiAutoCompleteComponent, NguiAutoCompleteDirective } from '@ngui/auto-complete';

@Component({
  // ...
  imports: [FormsModule, NguiAutoCompleteComponent, NguiAutoCompleteDirective],
})
export class MyComponent {}

NgModule (Angular 20 and below)

NguiAutoCompleteModule was removed in v21 — import the standalone component/directive shown above instead. If your app still relies on the NgModule, install the matching major and import the module as before:

• Angular 20 → npm install @ngui/auto-complete@20 (standalone, but NguiAutoCompleteModule is still re-exported for back-compat).
• Angular 19 and older → npm install @ngui/auto-complete@19.

import { NguiAutoCompleteModule } from '@ngui/auto-complete';

@NgModule({
  imports: [BrowserModule, FormsModule, NguiAutoCompleteModule],
})
export class AppModule {}

Usage

As a Directive

Attach to any element containing an input. The directive is a ControlValueAccessor, so it binds with [(ngModel)] like any form control:

<!-- Directly on an input -->
<input ngui-auto-complete [(ngModel)]="myValue" [source]="myArray" />

<!-- On a wrapping div: put the value binding on the host element -->
<div ngui-auto-complete [(ngModel)]="myValue" [source]="myArray">
  <input />
</div>

Reactive forms

Because the directive is a ControlValueAccessor, [formControl] and formControlName work directly:

<input ngui-auto-complete [formControl]="cityControl" [source]="cities" />

<form [formGroup]="form">
  <input ngui-auto-complete formControlName="city" [source]="cities" />
</form>

As a Component

Use <ngui-auto-complete> directly, control its visibility with @if:

<input [(ngModel)]="myValue" (focus)="show = true" (blur)="show = false" />
@if (show) {
  <ngui-auto-complete
    [source]="myArray"
    [show-input-tag]="false"
    [show-dropdown-on-init]="true"
    [(value)]="myValue">
  </ngui-auto-complete>
}

Remote / Observable Source

<input ngui-auto-complete
  [(ngModel)]="address"
  [source]="searchFn"
  path-to-data="results"
  list-formatter="formatted_address"
  min-chars="2" />

searchFn = (keyword: string): Observable<any> => {
  return this.http.get(`https://api.example.com/search?q=${keyword}`);
};

Custom dropdown templates

Pass Angular ng-templates for custom rendering: itemTemplate (each row — receives the item as $implicit and the row index as index), headerTemplate (a header row), and loadingTemplate (shown while remote data loads). They work on both the component and the directive:

<input ngui-auto-complete [(ngModel)]="myValue" [source]="myArray"
  [itemTemplate]="row" [headerTemplate]="head" />

<ng-template #head>Suggestions</ng-template>
<ng-template #row let-item let-i="index">
  <strong>{{ i + 1 }}.</strong> {{ item.name }} — <em>{{ item.country }}</em>
</ng-template>

API Reference

One reference for both surfaces. The Applies to column says whether each option works on the directive ([ngui-auto-complete]), the component (<ngui-auto-complete>), or both. Every option keeps its kebab-case attribute name; numeric/boolean inputs accept both the attribute form (min-chars="2") and the bound form ([min-chars]="2").

Value & forms

How the selected value is read and written.

| Option | Type | Default | Applies to | Description | |--------|------|---------|------------|-------------| | [(ngModel)] / [formControl] / formControlName | T | — | Directive | The directive is a ControlValueAccessor, so the value flows through Angular forms. (ngModelChange) / the control's valueChanges fire on every accepted value | | [(value)] | T | — | Component | Two-way bindable selected value on the standalone component | | select-value-of | string | — | Directive | Commit this property's value on selection instead of the whole object |

Data & filtering

Where suggestions come from and how the keyword is matched.

| Option | Type | Default | Applies to | Description | |--------|------|---------|------------|-------------| | source | T[] \| string \| ((keyword) => Observable<T[]>) | — | Both | Required (input.required — omitting [source] is a compile-time error). Local array, URL string, or a function returning an Observable | | path-to-data | string | — | Both | Dot-path to the array in an HTTP response, e.g. data.results | | min-chars | number | 0 | Both | Minimum characters before fetching/filtering | | max-num-list | number | unlimited | Both | Maximum number of suggestions to show | | match-formatted | boolean | false | Both | Match the keyword against formatted values instead of the raw data | | ignore-accents | boolean | true | Both | Treat accented characters as their base characters when matching |

Display & formatting

How rows and the selected value are rendered.

| Option | Type | Default | Applies to | Description | |--------|------|---------|------------|-------------| | display-with | string \| ((item) => string) | item's value | Directive | Text shown in the input after selecting an object — a property name (display-with="name") or a function ([display-with]="fn") | | list-formatter | string \| ((item) => string) | — | Both | Format each dropdown row. String pattern (key) name or a function | | itemTemplate | TemplateRef | — | Both | ng-template for each dropdown row (context: $implicit = item, index = row index). Takes precedence over list-formatter | | headerTemplate | TemplateRef | — | Both | ng-template for a non-selectable header row | | loadingTemplate | TemplateRef | — | Both | ng-template shown while remote data loads (falls back to loading-text) | | loading-text | string | 'Loading' | Both | Text shown while fetching remote data | | blank-option-text | string | — | Both | Adds an empty first option with this label | | no-match-found-text | string | — | Both | Text shown when nothing matches. Set to "" to suppress the row entirely | | placeholder | string | — | Component | Placeholder for the component's internal input | | auto-complete-placeholder | string | — | Directive | Placeholder for the dropdown's (normally hidden) internal input |

Behavior

Interaction and selection behavior.

| Option | Type | Default | Applies to | Description | |--------|------|---------|------------|-------------| | accept-user-input | boolean | true | Both | Allow values that are not in the list | | auto-select-first-item | boolean | false | Both | Pre-highlight the first suggestion | | select-on-blur | boolean | false | Both | Select the highlighted item on blur | | tab-to-select | boolean | true | Both | Select the highlighted item on the Tab key | | re-focus-after-select | boolean | true | Both | Return focus to the input after a selection | | autocomplete | boolean | false | Both | When false, sets the native autocomplete="off" on the input | | open-on-focus | boolean | true | Directive | Open the dropdown when the input gains focus | | close-on-focusout | boolean | true | Directive | Close the dropdown on focusout | | show-input-tag | boolean | true | Component | Render an <input> inside the component | | show-dropdown-on-init | boolean | false | Component | Open the dropdown as soon as the component appears |

Layout & positioning

| Option | Type | Default | Applies to | Description | |--------|------|---------|------------|-------------| | open-direction | 'auto' \| 'up' \| 'down' | 'auto' | Both | Preferred side. For the directive (CDK overlay) up/down set the preference and the overlay still flips when there isn't room; for the component, up renders above via CSS and auto/down keep it below | | z-index | number | 1 | Directive | z-index of the dropdown overlay. Rarely needed — the CDK overlay already renders above page content; only useful to order overlapping overlays |

RTL: there is no RTL input — the directive's overlay follows the input's computed direction, and the component's drop-up anchors via logical CSS (inset-inline-start). Just set dir="rtl" on the element or an ancestor (or the document direction).

Events

Both surfaces emit the same two outputs.

| Output | Payload | Applies to | Description | |--------|---------|------------|-------------| | (valueSelected) | NguiAutoCompleteSelection | Both | Fires when a value is committed. Use fromSource to tell a list pick from a typed value | | (noMatchFound) | void | Both | Fires when the filtered list is empty and the min-chars threshold is met — use it to show an "Add new…" affordance |

The (valueSelected) payload:

interface NguiAutoCompleteSelection<T = any> {
  value: T;          // the committed value (same as [(ngModel)] / [(value)])
  item: T;           // the full picked object (or the typed text)
  index: number;     // row in the shown list; -1 when typed (fromSource = false)
  fromSource: boolean; // true = picked from [source]; false = typed by the user
}

Type inference

NguiAutoCompleteComponent<T = any> is generic. Bind a typed [source] (a typed array or a function returning Observable<T[]>) and Angular infers the item type — [(value)], (valueSelected) (NguiAutoCompleteSelection<T>) and the itemTemplate context are then all typed with no extra annotation:

<ngui-auto-complete [source]="cities" [(value)]="city" (valueSelected)="onPick($event)"></ngui-auto-complete>

cities: City[] = [/* … */];
city?: City;
onPick(e: NguiAutoCompleteSelection<City>) { /* e.item is City */ }

It defaults to any, so existing templates are unaffected. The directive ([ngui-auto-complete]) stays loosely typed — Angular can't infer a generic for an attribute directive in templates, so its (valueSelected) payload is NguiAutoCompleteSelection<any>.

Theming

Restyle the dropdown by overriding these CSS variables. Each has a sensible default, so set only what you need. Set them on :root — the directive's dropdown renders in an overlay at the document root, so variables on an ancestor of the input won't reach it.

| Variable | Default | Controls | |----------|---------|----------| | --ngui-ac-background | #fff | Dropdown background | | --ngui-ac-color | inherit | Text color | | --ngui-ac-border | 1px solid rgba(0,0,0,.12) | Dropdown border | | --ngui-ac-border-radius | 4px | Corner radius | | --ngui-ac-shadow | 0 4px 12px rgba(0,0,0,.15) | Elevation shadow | | --ngui-ac-max-height | 256px | Height cap (none to remove) | | --ngui-ac-z-index | 10 | Stacking order of the floating list (standalone <ngui-auto-complete>; the directive's overlay uses the z-index input instead) | | --ngui-ac-item-padding | 6px 12px | Row padding (density) | | --ngui-ac-item-border | 1px solid rgba(0,0,0,.06) | Row divider | | --ngui-ac-hover-background | rgba(0,0,0,.06) | Row hover background | | --ngui-ac-selected-background | rgba(0,0,0,.1) | Highlighted row background |

/* e.g. a dark dropdown */
:root {
  --ngui-ac-background: #2b2b2b;
  --ngui-ac-color: #eee;
  --ngui-ac-item-border: 1px solid rgba(255, 255, 255, 0.08);
  --ngui-ac-hover-background: rgba(255, 255, 255, 0.08);
  --ngui-ac-selected-background: rgba(255, 255, 255, 0.16);
}

Angular Version Compatibility

This library follows Angular's versioning: @ngui/[email protected] supports Angular N. Install the version matching your Angular major (e.g. Angular 22 → npm install @ngui/auto-complete@22).

Development

Quick start

git clone https://github.com/ng2-ui/auto-complete.git
cd auto-complete
npm install

# Build library in watch mode, then in a second terminal start the demo app
npm run build-lib:watch
npm start

Available scripts

| Script | Description | |--------|-------------| | npm start | Serve the demo app on port 4200 | | npm test | Run unit tests (Karma/Jasmine) | | npm run lint | Lint all TypeScript and HTML | | npm run build-lib:watch | Build library in watch mode (for demo development) | | npm run build-lib:prod | Production library build | | npm run build-docs | Build demo app for GitHub Pages deployment | | npm run cypress:open | Open Cypress e2e test runner | | npm run cypress:run | Run Cypress e2e tests headlessly |

Publish a new version

# 1. Update version in projects/auto-complete/package.json
# 2. Build the library. This also copies README/CHANGELOG/MIGRATION/LICENSE
#    into dist/ for you (via the copy-lib script).
npm run build-lib:prod

# 3. Move into the built output — do NOT run npm publish from the project root
#    (the root package.json is private and will fail)
cd dist
npm publish --access public

Contributing — help wanted!

This library is maintained by a small team with limited time — every contribution genuinely helps keep it alive and improving. If you use it and find it useful, here are easy ways to give back:

• Found a bug? Open an issue with a clear description and a minimal reproduction
• Have an idea? Check the open issues first, then open a new one if needed
• Want to fix something? Pull requests are always welcome — small focused PRs are easiest to review
• Using it at work? A GitHub star goes a long way for visibility

Issues and pull requests: github.com/ng2-ui/auto-complete.

Changelog

See CHANGELOG.md for the full history of changes.

License

MIT