@ng-zi/extensions-autocomplete

MtxAutocomplete Component Overview

The MtxAutocomplete Component is a custom Angular component that extends and encapsulates the Angular Material autocomplete component. It provides enhanced features like custom item templates, flexible client/server filtering, and compatibility with Angular forms API. This component is designed to improve the user experience by offering infinite scroll, keyboard navigation, debounce input for server requests, and more.

Features

Feature	Description
Custom Item and 'Not Found' Templates	Easily customize the display of items and the 'not found' message.
Flexible Filtering	Supports both client-side and server-side filtering.
Form Compatibility	Works seamlessly with both Reactive and Template-driven forms.
Infinite Scroll	Load more items as the user scrolls down the list.
Keyboard Navigation	Navigate through the options using the keyboard.
Debounce Input	Reduce the number of server requests with input debouncing.
Clear Selection Button	Allow users to clear their current selection with a button.
Custom Error Handling	Handle errors gracefully with custom error handling.
Styling Enhancements	Style the component to match your application's look and feel.

Usage

Installation

1. Import the MtxAutocompleteModule into your Angular module:

   import { MtxAutocompleteModule } from '@ng-zi/extensions/autocomplete';
   
   @NgModule({
     declarations: [
       // your components
     ],
     imports: [
       // other modules
       MtxAutocompleteModule
     ],
     providers: [],
     bootstrap: [AppComponent]
   })
   export class AppModule { }

Example

Component TypeScript

import { Component } from '@angular/core';

@Component({
  selector: 'app-autocomplete-demo',
  templateUrl: './autocomplete-demo.component.html'
})
export class AutocompleteDemoComponent {
  filteredItems: string[] = ['One', 'Two', 'Three'];

  autocompleteconfig = {
    options: this.filteredItems,
    placeholder: 'Search items',
    displayWith: (value: string) => value,
    debounceTime: 300,
    infiniteScrollThreshold: 0.8,
    serverFiltering: false,
    clearButton: true
  };

  onOptionSelected(value: string) {
    console.log('Option selected:', value);
  }

  onSearchChange(value: string) {
    console.log('Search changed:', value);
  }

  onErrorHandling(error: any) {
    console.error('Error occurred:', error);
  }
}

Component HTML

<mtx-autocomplete 
  [autocompleteconfig]="autocompleteconfig" 
  (optionSelected)="onOptionSelected($event)" 
  (searchChange)="onSearchChange($event)" 
  (errorHandling)="onErrorHandling($event)">
</mtx-autocomplete>

Configuration Options

Option	Description
options	The list of options to display in the autocomplete dropdown.
displayWith	A function to control how the options are displayed in the input field.
placeholder	Placeholder text for the input field.
debounceTime	Time in milliseconds to debounce input changes.
infiniteScrollThreshold	Threshold for triggering infinite scroll, as a decimal fraction of the viewport height.
serverFiltering	Whether to use server-side filtering for options.
clearButton	Whether to display a clear button to clear the selection.

Events

Event	Description
optionSelected	Event emitted when an option is selected.
searchChange	Event emitted when the search input changes.
errorHandling	Event emitted when an error occurs.

Templates

Template	Description
notFoundTemplate	Template to display when no options are found.
customItemTemplate	Template to customize how options are displayed in the dropdown.

Custom Templates

You can customize the look and feel of the items and the 'not found' message using Angular's ng-template syntax.

Custom Item Template

<ng-template #customItemTemplate let-item>
  <div class="custom-item">
    {{ item }}
  </div>
</ng-template>

Not Found Template

<ng-template #notFoundTemplate>
  <div class="not-found">
    No items found.
  </div>
</ng-template>

Using Custom Templates

Pass the custom templates to the MtxAutocompleteComponent using the autocompleteconfig object:

autocompleteconfig = {
  options: this.filteredItems,
  placeholder: 'Search items',
  customItemTemplate: this.customItemTemplate,
  notFoundTemplate: this.notFoundTemplate,
  debounceTime: 300,
  infiniteScrollThreshold: 0.8,
  serverFiltering: false,
  clearButton: true
};

<mtx-autocomplete 
  [autocompleteconfig]="autocompleteconfig" 
  (optionSelected)="onOptionSelected($event)" 
  (searchChange)="onSearchChange($event)" 
  (errorHandling)="onErrorHandling($event)">
</mtx-autocomplete>

<ng-template #customItemTemplate let-item>
  <div class="custom-item">
    {{ item }}
  </div>
</ng-template>

<ng-template #notFoundTemplate>
  <div class="not-found">
    No items found.
  </div>
</ng-template>

Summary

The MtxAutocomplete Component provides a powerful and flexible way to implement autocomplete functionality in your Angular applications. With its customizable templates, filtering options, and seamless integration with Angular forms, it offers a rich user experience tailored to your needs.