@bbortt/ngx-autocomplete

Angular V11 compatible autocomplete component to use with any style framework.

Highlights:

• Fully flexible for any autocomplete object through propertyAccessor function
• Scales perfectly to every screen size, even when resizing
• Navigable using the mouse or keyboard (see Navigation)
• Create your own filter method which matches the case best
• Fits into the @angular/forms / FormGroup setup
• Customizable styling using css classes

>> Life Samples.

Contents

• Getting Started
• API Reference
  • Inputs
  • Outputs
  • Css Classes
• Navigation
• Examples
  • Simple
  • Advanced
  • Bootstrap

Getting Started

Add the NgxAutocompleteModule to your app.module.ts like this:

[...]

import { NgxAutocompleteModule } from '@bbortt/ngx-autocomplete';

@NgModule({
  declarations: [ ... ],
  imports: [ ..., NgxAutocompleteModule ],
  bootstrap: [ ... ],
})
export class AppModule {
}

That's it. You can head into the code at this point! The component selector is named <ngx-autocomplete />.

API Reference

Inputs

Input	Type	Description	Default
id	string	The ID of the <input /> component. Mostly used to link any <label /> elements.
name	string	The <input /> element name. Makes the form accessible for screen readers.
placeholder	string	The typical default placeholder of the <input /> element. Displayed weak as long as no value present.	'Search.'
options	any[]	An array of options which could be selected.	[]
propertyAccessor	string or (option: T) => string	The object autocomplete (and display) property name. Or an accessor function, given the option.
navigateInfinite	boolean	If true then the arrow key navigation will never end. Thus restart from the beginning / end.	false
debounceTime	number	A debounce time in ms. This delays the filtering as long as the user types continuously.	0

Outputs

Input	Type	Description
autocompleteChanges	EventEmitter<string>	Event will be emitted whenever the filter value changes. The user is responsible for filtering his data and providing the updated options.

Css Classes

ngx-autocomplete-input: The autocomplete text input.

ngx-autocomplete-container: <div /> with absolute position, holding the possible autocomplete options.

ngx-autocomplete-option: Every <option /> of the autocomplete dropdown.

ngx-autocomplete-option-active: A single active option (not yet selected).

Navigation

Key	Meaning
arrow up / arrow down	Navigate through the options. May be infinite using navigateInfinite.
enter	Selects the current active option from the dropdown.
escape	Cancel the selection - this does not use the current active option.

Examples

All example autocompletes are deployed life: bbortt.github.io/ngx-autocomplete.

Simple

The easiest autocomplete is the pure string array.

autocomplete-sample.component.ts:

@Component({
  selector: 'app-autocomplete-sample',
  templateUrl: './autocomplete-sample.component.html'
})
export class AutocompleteSampleComponent implements OnInit {
  editForm = this.fb.group({
    country: ['', Validators.required]
  });

  private allOptions = ALL_COUNTRIES;
  options: string[] = [];

  constructor(private fb: FormBuilder) {}

  ngOnInit(): void {
    this.editForm
      .get('country')!
      .valueChanges.subscribe((value: string) => this.filter(value));
  }

  filter(value: string): void {
    this.options = this.allOptions.filter((option: string) =>
      option.startsWith(value)
    );
  }
}

autocomplete-sample.component.html

<ngx-autocomplete
  inputName="country"
  inputId="field-country"
  formControlName="country"
  [options]="options"
  (autocompleteChanges)="filter($event)"
></ngx-autocomplete>

Source.

Advanced

The advanced sample uses complex objects and the name property as an accessor. Take a look at the code in projects/bbortt/samples/src/app/sample-advanced.

Bootstrap

The bootstrap sample lives up to its name. Using a custom .scss styling, it extends the Bootstrap form styles. Take a look at the code in projects/bbortt/samples/src/app/sample-bootstrap.

License

This project is licensed under the terms of the Apache 2.0 License.