2.0.12 • Published 2 years ago

angular-ng-autocomplete v2.0.12

Weekly downloads
11,906
License
MIT
Repository
github
Last release
2 years ago

Angular Autocomplete

Table of contents

Features

  • Flexible autocomplete with client/server filtering.
  • Variable properties and event bindings.
  • Selection history.
  • Custom item and 'not found' templates.
  • Infinite scroll.
  • Compatible with Angular forms API (Both Reactive and Template-driven forms).
  • Keyboard navigation.
  • Accessibility.

Getting started

Step 1: Install angular-ng-autocomplete:

NPM

npm i angular-ng-autocomplete

Step 2: Import the AutocompleteLibModule:

import {AutocompleteLibModule} from 'angular-ng-autocomplete';

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

Usage sample

<div class="ng-autocomplete">
<ng-autocomplete 
  [data]="data"
  [searchKeyword]="keyword"
  placeholder="Select country"
  (selected)='selectEvent($event)'
  (inputChanged)='onChangeSearch($event)'
  (inputFocused)='onFocused($event)'
  [itemTemplate]="itemTemplate"
  [notFoundTemplate]="notFoundTemplate">                                 
</ng-autocomplete>

<ng-template #itemTemplate let-item>
<a [innerHTML]="item.name"></a>
</ng-template>

<ng-template #notFoundTemplate let-notFound>
<div [innerHTML]="notFound"></div>
</ng-template>
</div>
class TestComponent {
  keyword = 'name';
  data = [
    {
      id: 1,
      name: 'Georgia'
    },
     {
       id: 2,
       name: 'Usa'
     },
     {
       id: 3,
       name: 'England'
     }
  ];


  selectEvent(item) {
    // do something with selected item
  }

  onChangeSearch(val: string) {
    // fetch remote data from here
    // And reassign the 'data' which is binded to 'data' property.
  }
  
  onFocused(e){
    // do something when input is focused
  }
}

API

Inputs

InputTypeDefaultRequiredDescription
dataArray<any>nullyesItems array. It can be array of strings or array of objects.
searchKeywordstring-yesVariable name to filter data with.
customFilter(items: any[], query: string) => any[]undefinednoCustom filter function. You can use it to provide your own filtering function, as e.g. fuzzy-matching filtering, or to disable filtering at all (just pass (items) => items as a filter). Do not change the items argument given, return filtered list instead.
selectedValueRender(value: any) => stringundefinednoCustom renderer function to render selected value inside input field.
placeholderstring-noHTML <input> placeholder text.
headingstring-noHeading text of items list. If it is null then heading is hidden.
initialValueany_noInitial/default selected value.
focusFirstbooleanfalsenoAutomatically focus the first matched item on the list.
historyIdentifierstring_noHistory identifier of history list. When valid history identifier is given, then component stores selected item to local storage of user's browser. If it is null then history is hidden. History list is visible if at least one history item is stored. History identifier must be unique.
historyHeadingstringRecently selectednoHeading text of history list. If it is null then history heading is hidden.
historyListMaxNumbernumber15noMaximum number of items in the history list.
notFoundTextstringNot foundnoSet custom text when filter returns empty result.
isLoadingbooleanfalsenoSet the loading state when data is being loaded, (e.g. async items loading) and show loading spinner.
minQueryLengthnumber1noThe minimum number of characters the user must type before a search is performed.
debounceTimenumber_noDelay time while typing.
disabledbooleanfalsenoHTML <input> disable/enable.

Outputs

OutputDescription
(selected)Event is emitted when an item from the list is selected.
(inputChanged)Event is emitted when an input is changed.
(inputFocused)Event is emitted when an input is focused.
(inputCleared)Event is emitted when an input is cleared.
(opened)Event is emitted when the autocomplete panel is opened.
(closed)Event is emitted when the autocomplete panel is closed.
(scrolledToEnd)Event is emitted when scrolled to the end of items. Can be used for loading more items in chunks.

Methods (controls)

NameDescription
openOpens the autocomplete panel
closeCloses the autocomplete panel
focusFocuses the autocomplete input element
clearClears the autocomplete input element

To access the control methods of the component you should use @ViewChild decorator. See the example below:

<ng-autocomplete #auto></ng-autocomplete>
class TestComponent {
  @ViewChild('auto') auto;

  openPanel(e): void {
    e.stopPropagation();
    this.auto.open();
  }
  
  closePanel(e): void {
    e.stopPropagation();
    this.auto.close();
    }
    
  focus(e): void {
    e.stopPropagation();
    this.auto.focus();
  }  
}

Styles

If you are not happy with default styles you can easily override them:

<div class="ng-autocomplete">
<ng-autocomplete></ng-autocomplete>
</div>
.ng-autocomplete {
    width: 400px;
}

Support Angular autocomplete!

If you do love angular-ng-autocomplete I would appreciate a donation :)

npm.io

Author

License

MIT