ng-autocomplete-plugin v2.1.4

Angular Autocomplete

A simple, powerful, lightweight and customizable autocomplete tool programmed for Angular projects.

Recommended Angular version

Angular 14+

Whats better in this package?

• Lightweight module
• No 3rd party packages installed
• Ability to use 3rd party style packages like bootstrap, tailwind or any css libraries. (You can update the classes from your component)
• No angular material or cdk library
• Supports large data set
• Customizable scroll functionality
• Supports custom events
• Easy virtual scrolling for large data set without 3rd party
• Custom classes and ng-styles are allowed
• Keyboard navigation events to scroll through dropdown list
• 22+ solid test cases to validate the module
• Eventful module.

Web documentation

Documentation is now available on modulejs.org

What's new in ^2.0.0?

• Search algorithm has been redefined without impacting prior versions.
• Added View More to List dropdown at the end of the list as an alternative to call API when reaching the end of scroll.
• Now the developers who consume this package can decide how they should trigger an API Call. Using View More, or triggering API Call when reaching end of scroll. Both can be configured as well. Refer below for more information.
• Renamed the internal class loader to autocomplete-plugin-loader as loader class is too common name and may collide with other libraries.
• Updated scroll event and resize event by using Renderer2 to efficiently manage the event listeners.
• Added ARIA label by introducing an input property ariaViewMore.
• Added keyboard navigation events to scroll through dropdown list and select the list when pressing Enter Key

How to make best use of this package ?

Read the full documentation without skipping, to know the flexibility of this module and refer the examples provided. Apart from the general use, this package comes handy when

• Lazy loading is required. A custom function can be executed from the application which may be an API call with offset or paginated params or any other custom function that is suitable for the requirement.
• Effortless styling of the input field and dropdown using custom css, or with libraries like bootstrap, tailwind and so on.
• Handling large dataset with or without lazy load configuration
• When triggerApiLoadEvent is set to true, its developers responsibility to set it as false once the custom function is executed and expected result is achieved.
• If totalRecords is known during the initialization of the module, the module will act pro-actively based on this input and will not call any custom functions once the totalRecords match the actual dropdownData and when scroll is complete.

Installation

Install ng-autocomplete-plugin with npm

  npm install ng-autocomplete-plugin --save

  or

  npm i ng-autocomplete-plugin

Running Tests

ng-autocomplete-plugin has 20+ solid test cases to make sure components executes without any issues.

To run tests, run the following command

  npm run test
  or
  ng test

Package version

Demo & Examples

API Usage

Input decorators

Output decorators

Using the module

import NgAutocompletePluginModule into your app module.

import { NgAutocompletePluginModule } from 'ng-autocomplete-plugin';

In your HTML template

For dropdown string array,Eg: "Apple", "Banana", "Kiwi", do as below.

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)">
</ng-autocomplete>

For dropdown object array, Eg: {"name": "Alex"}, {"name": "John"}, do as below.

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
    [objectProperty]="'name'">
</ng-autocomplete>

To control the width of autocomplete, wrap a div and specify the width. Custom CSS classes can also be used(Scroll below).

<div style="width: 200px">
    <ng-autocomplete
        [dropdownData]="YOUR_DROPDOWN_DATA"
        (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
        [objectProperty]="'name'">
    </ng-autocomplete>
</div>

Setting scrollThreshold & initialVisibleData for maximizng performance

By default, initialVisibleData is set to 1000 and scrollThreshold is set to 3. It can be customized as per requirement.

What is scrollThreshold & initialVisibleData?

Both scrollThreshold & initialVisibleData helps to improve virtual scrolling for better performance.

initialVisibleData is the number of records / data that will be loaded virtually during initial load.

Consider, there are 5000 records to be shown. initialVisibleData is 1000 and scrollThreshold is 3.

During initial load, dropdown list will show 1000 records. When user reaches the end of scroll, the formula will be calculated based on initialVisibleData & scrollThreshold and number of filteredData records.

Math.ceil(filteredData.length /scrollThreshold);

Math.ceil(1000/3);

If calculated result does not exceed initialVisibleData, next set of data will be loaded. And now the dropdown list(filteredData) will hold 2000 records.

Similary same calculation will be performed during the end of scroll and when the result exceeds initialVisibleData, first set of records will be removed from the dropdown list and next set of records will be loaded everytime, to improve performance.

When scrollThreshold is set to 1, the virtual dropdown list will hold the records based on initialVisibleData configuration. When end of scroll is reached, the current set will be replaced by next set.

initialVisibleData & scrollThreshold does not affect or mutate original data and will update only the virtually filtered data.

initialVisibleData & scrollThreshold is customizable based on project needs. If this performance calculation is not required, set isScrollThresholdRequired to false.

CSS Classes used in npm-autocomplete-plugin html template

This is for informational purpose only. Be cautious if you are overriding these CSS as it may affect dropdown style if updated incorrectly.

It is always recommended to add class through customClass or customStyle Input() properties.

Adding Custom CSS Class to autocomplete

Import CustomClassType from the module (Optional).

import CustomClassType Type into your app, to see the custom class types available. Its optional, but would be good to use. Write your custom class in global css file or use ::ng-deep from specific components.

import { CustomClassType } from 'ng-autocomplete-plugin';

In your template, do the following:

customClassType: CustomClassType = {
    inputFieldClass: 'class1',
    dropdownListClass: 'class1 class2'
}

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
    [objectProperty]="'name'"
    [customClassType]="customClassType">
</ng-autocomplete>

Adding Custom NgStyle to autocomplete

Import CustomNgStyleType from the module (Optional).

import CustomNgStyleType Type into your app, to see the custom class types available. Its optional, but would be good to use.

import { CustomNgStyleType } from 'ng-autocomplete-plugin';

In your template, do the following:

customClassType: CustomNgStyleType = {
    inputFieldStyle: {color: '#FFFFFF' },
    dropdownListStyle: {padding: 2px }
}

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
    [objectProperty]="'name'"
    [customClassType]="customClassType">
</ng-autocomplete>

Adding custom Spinner

To add a custom spinner, do the following. Recommended to use custom spinner to have better control of project requirement.

Update @Input() properties like below

showLoadingSpinner = true; // Turn this ON so that module will show the spinner. By default it is ON (true)

isCustomSpinner = true;

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
    [showLoadingSpinner]="true"
    [isCustomSpinner]="true">
    <span customSpinner class="YOUR_CLASS"> </span>
</ng-autocomplete>

customSpinner in the span represents ng-content select attribute

Using custom content in the input textfield

A flexible option is provided to add custom functionality in the input text field.

<ng-autocomplete
    [dropdownData]="YOUR_DROPDOWN_DATA"
    (emitSelectedValue)="YOUR_CUSTOM_FUNTION($event)"
    [showdropDownArrow]="false"
    [showClearOption]="false">
    <span textField class="YOUR_CLASS">YOUR_CONTENT</span>
</ng-autocomplete>

showdropDownArrow and showClearOption can be set as false for better placement of the customized ng-content.

textField in the span represents ng-content select attribute

Adding Accessible Rich Internet Applications (ARIA)

ARIA provides easy access to the content for people with disabilities with help of screen reader.

Change Logs and version history

Refer the change history by viewing this link - CHANGELOG

Github link

Github Link - ng-autocomplete-plugin

Support

Please raise an issue in github repository

Github Link - Raise an issue

Roadmap

• Multiselect dropdown before Q1 2025
• Extensive search - Ability to search entire object in the list