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.