ngx-ion-autocomplete

A mobile-friendly autocomplete component for Ionic Angular that opens a search modal.
It integrates seamlessly with Angular Reactive Forms (ControlValueAccessor) and is designed for object selection from a paginated search service.

✨ Features

• Fully Ionic-based UI: ion-searchbar, ion-list, ion-item, skeleton loader, “no result” state.
• Opens a modal with automatic searchbar focus.
• Pagination-ready: search service receives both query and page.
• Works with any object type returned by your API.
• ControlValueAccessor implementation — bind directly to your form controls.
• Internationalization via @jsverse/transloco.

Installation

npm install @xevlabs/ion-autocomplete

Usage

<ngx-ion-autocomplete
  [displayedKey]="'name'"
  [searchService]="customerSearchService"
  [key]="'customers'"
  formControlName="customer">
</ngx-ion-autocomplete>

Required inputs

• displayedKey: string
  The property name to display in the default item template.
• key: string
  i18n key namespace used for labels (modal title, placeholders, etc.).
  Example keys automatically used:
  • ${key}.SEARCH_LIST_LABEL
  • ${key}.NO_ITEM_FOUND
• One of:
  • searchService: (query: string) => Observable<any[]> | Promise<any[]>
    Function returning results.
  • data: any[]
    Static array of options.

Other inputs

• multiple?: boolean – enable multiple selection
• modalTitle?: string – override the modal title
• debounce?: number – debounce time for queries (ms)
• maxSelectedItems?: number – limit the number of selected items
• placeholder?: string – placeholder in the search input
• disabled?: boolean – disable the component

Custom templates (items & loader)

From commit 1bdf177, you can customize both the result item content and the loading state.

New inputs

• resultItemTemplate?: TemplateRef<any> – template for each result item.
• loadingItemTemplate?: TemplateRef<any> – template for skeleton/loading rows.

Context

• Item template: { item } → use let-item="item"
• Loader template: no context

⚠️ Your templates are rendered inside the library’s <ion-item>.
Do not wrap them in another <ion-item>; just provide the inner content (like <ion-label>…</ion-label>).

Example

<!-- Custom item content -->
<ng-template #itemTpl let-item="item">
  <ion-label class="ion-text-wrap">
    <div class="text-base">{{ item.name }}</div>
    <div class="ion-text-muted" *ngIf="item.email">{{ item.email }}</div>
  </ion-label>
  <ion-badge slot="end" *ngIf="item.role">{{ item.role }}</ion-badge>
</ng-template>

<!-- Custom loader content -->
<ng-template #loadTpl>
  <ion-label>
    <ion-skeleton-text [animated]="true" style="width: 50%"></ion-skeleton-text>
  </ion-label>
</ng-template>

<!-- Component -->
<ngx-ion-autocomplete
  [displayedKey]="'name'"
  [searchService]="customerSearchService"
  [key]="'customers'"
  [resultItemTemplate]="itemTpl"
  [loadingItemTemplate]="loadTpl"
  formControlName="customer">
</ngx-ion-autocomplete>

Defaults

If no templates are provided:

• Result item:

  <ion-label>{{ item[displayedKey] }}</ion-label>

• Loader:

  <ion-label>
    <ion-skeleton-text [animated]="true" style="width: 80%"></ion-skeleton-text>
  </ion-label>

Styling

The component uses Ionic components (ion-item, ion-label, ion-badge, ion-spinner, ion-skeleton-text, etc.),
so you can customize styles globally via Ionic theming.

Internationalization (i18n)

The key input is required. The component looks up translations using the following keys:

• ${key}.SEARCH_LIST_LABEL – Modal title label
• ${key}.NO_ITEM_FOUND – Label when no result matches

You can integrate with ngx-translate or any i18n system.

Roadmap

• ✅ Async search with debounce
• ✅ Multiple selection
• ✅ Custom templates for result items and loader
• ⏳ Virtual scroll for large datasets
• ⏳ Better accessibility support

License

MIT © Xevlabs

🧰 Troubleshooting

• 'ion-...' is not a known element → Import IonicModule in the current module.
• Can't bind to 'formControl' → Import ReactiveFormsModule.
• No text for “No result” → Ensure Transloco is configured and autocomplete.noResult is defined.

📜 Public API

In public-api.ts:

export * from './lib/ngx-ion-autocomplete.component';
export * from './lib/ngx-ion-autocomplete.module';

(Models are not exported.)