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
• No 3rd party packages installed
• 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
• Ability to use 3rd party style packages like bootstrap, tailwind or any css libraries. (You can update the classes from your component)
• 22+ solid test cases to validate the module
• Eventful module.

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

| ng-autocomplete-plugin version | Description | | :-------- | :-----------| | 1.0.3 | Recommended. Updated readme file with few changes. | | 1.0.2 | Recommended. Only Read me file updated. | | 1.0.1 | First major version |

Demo & Examples

| Demo Description | Stackblitz Example | | :-------- | :-----------| | Autocomplete Example | Autocomplete - Stackblitz | | API Call Event Example | Autocomplete with API call event - Stackblitz | | Autocomplete With Bootstrap | Autocomplete with bootstrap| | Autocomplete With Tailwind | Autocomplete with tailwind| | Turn off performance calculation during scroll | Turn off performance calculation during scroll| | Disabling a list in dropdown| Disabling a list in dropdown|

API Usage

Input decorators

| Input | Type | Required | Description | | -------- | ------- | ------- | ------- | | dropdownData | string[] or object[] | Yes. | Accepts array of strings or numbers or array of objects | | | objectProperty | string |Yes | Required only if dropdownData is object[]. Helps to display dropdown value in dropdown list. | | placeholder | string | No | Custom placeholder for auto-complete. | | defaultValue | string or object | No | To pre-select a value from dropdown. | | initialVisibleData | number| No | Displays 1000 records in dropdown by default. Can be changed as per project convenience. | | scrollThreshold | number | No | 3 by default. Helps to boost performance. It controls the scroll data and removes top or botton records during user scroll based on the scrollThreshold & initialVisibleData configured. Check below for more details. | |totalRecords | number | No | If total number of records is known, totalRecords can be provided which will avoid extra events getting executed. |disableProperty | string | No | To disable specific dropdown list item in dropdown. User cannot select the dropdown if disabled. This property can be used for object[] dropdown and disableProperty should be one of the boolean property in object| |disableListFn |Function |No | If disable a list item should be calculated dynamically using a function and custom code, assign customized function to disableListFn. disableListFn accepts two parameters (index, data)| |searchFn |Function |No | Customized search function. Customized search function accepts one parameter, event. On keyUp, the customized search function will be called to perform custom execution.| |isNumber |boolean |No | If the displayed list is number, then sending isNumber as true will help to search the list efficiently | |noSearchResultMessage |string |No | By default No results found message will be displayed when search result is 0. It can be changed with this input property. | |customTrackBy | Function |No | Custom ngFor trackBy Function| |isAutoCompleteDisabled |boolean |No | Default value is false. If updated as true, the input field gets disabled. | |customClass | object |No | Allows custom class styling at various dom levels. Check below for more information | |customStyle | object |No | Allows custom ng-style. Check below for more information | |showdropDownArrow | boolean |No | Default is true. Show or hide dropdown icon in autocomplete field. | |showClearOption |boolean |No | Default is true. Shows clear option to allow the user to reset or clear the selected value. | |showLoadingSpinner | boolean|No | Default is false. Shows the spinner at the botton of the list if lazy loaded. Use custom spinner for better flexibility and make sure showLoadingSpinner is set to true for custom spinner. | | triggerBlurEvent|boolean |No | Default is false. When set to true, it emits an output event emitBlurEvent during focusOut | |triggerApiLoadEvent |boolean |No | Default is false. If dropdown list is loaded through API via lazy loading, this can be set as true, it emits an event emitApiLoadEvent. When the output event is emitted, user can take care of loading the dropdown data further.| |triggerAutoCompleteOpenEvent |boolean |No | Default is false. When set to true, it emits an output event emitAutoCompleteOpenEvent when auto-complete dropdown list opens. | |triggerSearchEvent |boolean |No | Default is false. When set to true, emits an output event emitSearchEvent whenever user types and search. | |triggerClearSelectionEvent |boolean |No | Default is false. When set to true, emits an output event emitClearSelectedEvent whenever selected field is cleared. | |isScrollThresholdRequired|boolean|No | Default is true. If initialVisibleData and scrollThreshold is performance calculation is not required, set it to false. See below for more information.|

Output decorators

| Output | Required | Description | | -------- | ------- | ------- | |emitSelectedValue |Yes |Emits the selected dropdown value. | |emitApiLoadEvent |No | To load next set of dropdownData using API or any other external means. Emits event when end of scroll is reached.triggerApiLoadEvent needs to be set to true to emit this event. | |emitAutoCompleteOpenEvent |No | Emits event when dropdown is opened or displayed. triggerAutoCompleteOpenEvent needs to be set to true to emit this event.| |emitClearSelectedEvent |No | Emits event when selected value is cleared. triggerClearSelectionEvent needs to be set to true to emit this event.| |emitBlurEvent |No | Emits event during focus out. triggerBlurEvent needs to be set to true to emit this event.|

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. Make sure you use ::ng-deep or host when updating the internal css or by turning off encapsulation.

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

| Classes | Description | Comments | | :-------- | :-----------| :-----------| | auto-complete-textfield-container | Class of parent html div template | Able to override through parentContainerClass or parentContainerStyle | | label-container | Class of label tag |Able to override through inputLabelContainerClass or inputLabelContainerStyle | | label-value | Class of <label> tag |Able to override through inputLabelClass or inputLabelStyle | | field-container | Class of div that surrounds input field and autocomplete li | Able to override through inputFieldContainerClass or inputFieldContainerStyle | | auto-complete-textfield | Class of input text field| Able to override through inputFieldClass or inputFieldStyle | auto-complete-list | Class of div that surrounds li|Able to override through listContainerClass or listContainerStyle | | unorder-list | Class of ul |Able to override through dropdownUnorderedListClass or dropdownUnorderedListStyle | | autocomplete-data-list | Class of li |Able to override through disableListClass or dropdownListStyle | | autocomplete-data-list noSearchResult | Class of li if search result not found. |Able to override through noResultClass or noResultStyle |

Adding Custom CSS Class to autocomplete

Import CustomClassType from the module (Optional).

| CustomClassTypes | Required | Description | | :-------- | :-----------| :-----------| | parentContainerClass | No | Adds class to div surrounding the input field and dropdown list. | | inputFieldContainerClass | No | Adds class to the parent div of input field | | inputFieldClass | No | Adds class to input textfield| | listContainerClass | No | Adds class to div that surrounds ul of dropdown list. | | dropdownUnorderedListClass | No | Adds class to ul of dropdown list. | | dropdownListClass | No | Adds class to each li items| | noResultClass | No | Adds class to separate li item to show no result message. | | disableListClass | No | Adds class to each li items. Depends on disableListFn function or disableProperty | | inputLabelClass | No | Adds class to <label> field | | inputLabelContainerClass | No | Adds class to parent div of <label> field |

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

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).

| CustomNgStyleTypes | Required | Description | | :-------- | :-----------| :-----------| | parentContainerStyle | No | Adds style to div surrounding the input field and dropdown list. | | inputFieldContainerStyle | No | Adds style to the parent div of input field | | inputFieldStyle | No | Adds style to input textfield| | listContainerStyle | No | Adds style to div that surrounds ul of dropdown list. | | dropdownUnorderedListStyle | No | Adds style to ul of dropdown list. | | dropdownListStyle | No | Adds style to each li items| | noResultStyle | No | Adds style to separate li item to show no result message. | | inputLabelStyle | No | Adds style to <label> field | | inputLabelContainerStyle | No | Adds style to parent div of <label> field |

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.

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 passed 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.

| Attributes | Decorator | Required | Description | | :-------- | :-----------| :-----------|:-----------| | ariaRole | @Input | No | Adds ARIA role to input textfield | | ariaInputField | @Input | No | Adds ARIA label to input textfield| | ariaNoSearchResult | @Input | No | Adds ARIA label to no result found li item| | ariaULList | @Input | No | Adds ARIA label to ul list item | | ariaListContainer | @Input | No | Adds ARIA label to list container div. | | ariaInputLabel | @Input | No | Adds ARIA label to label field. |

Support

Please raise an issue in github, if you find any.

Roadmap

Will deploy more features in future.

Will be working on adding similar autocomplete feature in VUE and React.

Github link

Github Link - ng-autocomplete-plugin