Ngb-Select (Angular Bootstrap Select Component)

A comprehensive, lightweight Angular Standalone select component that utilizes pure Bootstrap 5 classes (no external UI libraries required). It covers all advanced features found in modern select components, optimized for standard Bootstrap environments.

🚀 Features at a Glance

• 📦 Standalone Architecture - Modern Angular 15+ design, easy to import without NgModules.
• 🎨 Pure Bootstrap 5 - Uses .form-select, .dropdown-menu, and .list-group internally. No extra CSS payload.
• 🔍 Filtering & Match Modes - Fast, client-side search supporting contains, startsWith, endsWith, equals.
• 🗂️ Grouping - Categorize options with nested headers.
• 🛠️ Advanced Templating - Replace default text with fully custom DOM for items, headers, footers, and selected states.
• ⌨️ Forms Native & Signals - Implements ControlValueAccessor for seamless ngModel, FormControl (Reactive Forms), and modern Angular model() Signal support.
• 🛡️ Robust Fallbacks - Defensively programmed to gracefully handle null, undefined, and empty strings across inputs.
• ♿ Accessible - ARIA roles implemented (combobox, listbox, option) alongside keyboard navigation.
• ⚡ Editable Combobox - Allows custom user typing directly into the select input.
• 🎯 Focus on Open - Programmatically scroll and focus a specific option index when the popup opens.

📦 Installation

Install @amro93/ngb-select along with peer dependencies:

npm install @amro93/ngb-select bootstrap bootstrap-icons

Ensure Bootstrap 5 CSS is included in your angular.json or src/styles.scss:

@import 'bootstrap/scss/bootstrap';
@import 'bootstrap-icons/font/bootstrap-icons.css';

💻 Usage Examples

1. Basic Setup (Template Driven)

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { NgbSelectComponent } from '@amro93/ngb-select';

@Component({
  standalone: true,
  imports: [NgbSelectComponent, FormsModule],
  template: `
    <ngb-select
      [options]="cities"
      [(ngModel)]="selectedCity"
      optionLabel="name"
      optionValue="code"
      placeholder="Select a City"
    >
    </ngb-select>
  `,
})
export class AppComponent {
  cities = [
    { name: 'New York', code: 'NY' },
    { name: 'Rome', code: 'RM' },
    { name: 'London', code: 'LDN' },
  ];
  selectedCity: string = 'NY';
}

2. Reactive Forms with Validation

import { Component } from '@angular/core';
import { ReactiveFormsModule, FormGroup, FormControl, Validators } from '@angular/forms';
import { NgbSelectComponent } from '@amro93/ngb-select';

@Component({
  standalone: true,
  imports: [NgbSelectComponent, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <ngb-select
        [options]="countries"
        formControlName="selectedCountry"
        optionLabel="name"
        optionValue="code"
        [invalid]="form.get('selectedCountry')?.invalid && form.get('selectedCountry')?.touched"
        [showClear]="true"
        placeholder="Select Country"
      >
      </ngb-select>
    </form>
  `,
})
export class AppComponent {
  form = new FormGroup({
    selectedCountry: new FormControl(null, [Validators.required]),
  });
}

3. Filtering and Custom Search Modes

<ngb-select
  [options]="countries"
  [(ngModel)]="selectedCountry"
  optionLabel="name"
  [filter]="true"
  filterBy="name,code"
  filterMatchMode="startsWith"
  filterPlaceholder="Search countries..."
  [showClear]="true"
  placeholder="Select a Country"
>
</ngb-select>

4. Custom Templating

Override default rendering for options and the selected value using <ng-template>:

<ngb-select [options]="users" [(ngModel)]="selectedUser" optionLabel="name">
  <!-- Custom Selected Item -->
  <ng-template #selectedItem let-user>
    <div class="d-flex align-items-center gap-2">
      <img [src]="user.avatar" class="rounded-circle" width="22" height="22" />
      <strong>{{ user.name }}</strong>
    </div>
  </ng-template>

  <!-- Custom Dropdown Item -->
  <ng-template #item let-user>
    <div class="d-flex align-items-center justify-content-between w-100 py-1">
      <div class="d-flex align-items-center gap-2">
        <img [src]="user.avatar" class="rounded-circle" width="28" height="28" />
        <div>
          <div class="fw-semibold">{{ user.name }}</div>
          <small class="text-muted">{{ user.email }}</small>
        </div>
      </div>
      <span class="badge bg-primary-subtle text-primary-emphasis">{{ user.role }}</span>
    </div>
  </ng-template>
</ngb-select>

5. Searchable Multi-Select with Checkboxes & Chips

<ngb-select
  [options]="countries"
  [(ngModel)]="selectedCountries"
  optionLabel="name"
  optionValue="code"
  [multiple]="true"
  display="chip"
  [filter]="true"
  filterBy="name,code"
  searchPlaceholder="Search countries by name or code..."
  [showSelectAll]="true"
  [showClear]="true"
  placeholder="Select Countries"
>
</ngb-select>

6. Grouped Options

<ngb-select
  [options]="groupedCars"
  [(ngModel)]="selectedCar"
  [group]="true"
  optionGroupLabel="brand"
  optionGroupChildren="cars"
  optionLabel="name"
  optionValue="value"
  placeholder="Choose vehicle brand"
>
</ngb-select>

7. RTL (Right-to-Left) & Arabic Support

<div dir="rtl" lang="ar">
  <ngb-select
    [options]="arabicCountries"
    [(ngModel)]="selectedCountry"
    optionLabel="name"
    optionValue="code"
    [filter]="true"
    filterPlaceholder="ابحث عن دولة..."
    placeholder="اختر الدولة"
    emptyMessage="لا توجد نتائج"
  >
  </ngb-select>
</div>

📖 Documentation & Links

• 🌐 Live Demo & Showcase
• ⚡ StackBlitz Sandbox
• 📘 Architecture & Features Guide
• 📘 API & Interfaces Reference
• 📘 Installation & Setup Guide

📄 License

Distributed under the MIT License. See LICENSE for more information.