ng-bootstrap-multiselect

A lightweight, standalone Angular implementation of the PrimeNG MultiSelect component, rebuilt from the ground up to use Bootstrap 5 for styling and layout.

🚀 Features

• Zero PrimeNG Overhead: No need to import PrimeNG modules or themes.
• Bootstrap 5 Driven: Uses standard Bootstrap form classes, dropdown layouts, and badges.
• 1:1 PrimeNG API Parity: Identical @Input() and @Output() properties so you can swap seamlessly without modifying component code or logic.
• Standalone Component: Fully compatible with modern Angular (v18, v19, v20, v21+).
• Template Customization: Rich projection support for custom items, headers, footers, and selected item chips.
• Form Integration: Implements ControlValueAccessor for seamless reactive forms (formControlName) and ngModel binding.
• Accessible & Responsive: Supports keyboard navigation (Arrow keys, Enter, Escape, Space) and screen readers.

📦 Installation

Install the package via npm:

npm install ng-bootstrap-multiselect

Ensure Bootstrap 5 styles and Bootstrap Icons (optional for default loading icon) are included in your project:

npm install bootstrap bootstrap-icons

In your angular.json or main stylesheet:

/* styles.scss */
@import "bootstrap/scss/bootstrap";
@import "bootstrap-icons/font/bootstrap-icons.css";

💻 Quick Start

Import MultiSelectComponent into your standalone Angular component or module:

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { MultiSelectComponent } from 'ng-bootstrap-multiselect';

interface City {
  name: string;
  code: string;
}

@Component({
  selector: 'app-demo',
  standalone: true,
  imports: [FormsModule, MultiSelectComponent],
  template: `
    <div class="mb-3">
      <label class="form-label">Select Cities</label>
      <lib-multi-select
        [options]="cities"
        [(ngModel)]="selectedCities"
        optionLabel="name"
        placeholder="Select Cities"
        display="chip"
        [filter]="true"
      ></lib-multi-select>
    </div>
  `
})
export class DemoComponent {
  cities: City[] = [
    { name: 'New York', code: 'NY' },
    { name: 'Rome', code: 'RM' },
    { name: 'London', code: 'LDN' },
    { name: 'Istanbul', code: 'IST' },
    { name: 'Paris', code: 'PRS' }
  ];

  selectedCities: City[] = [];
}

📋 API Reference

@Input() Properties

| Input | Type | Default | Description | | :--- | :--- | :--- | :--- | | options | any[] | [] | An array of objects to display as selectable options. | | optionLabel | string \| null | null | Property name of an option to use as the display label. | | optionValue | string \| null | null | Property name of an option to use as the value. | | optionDisabled | string \| null | null | Property name to determine if an option is disabled. | | placeholder | string | 'Select Items' | Placeholder text when no items are selected. | | display | 'comma' \| 'chip' | 'comma' | Display mode for selected items. | | filter | boolean | false | Whether to show the filter/search input inside the dropdown. | | filterPlaceholder | string | 'Search' | Placeholder for the filter input field. | | maxSelectedLabels | number | 3 | Maximum items to display as text before summarizing with {0} items selected. | | selectedItemsLabel | string | '{0} items selected' | Summary label template used when selection count exceeds maxSelectedLabels. | | showClear | boolean | false | Shows a clear icon button to unselect all options. | | disabled | boolean | false | Disables the multiselect component. | | loading | boolean | false | Shows a loading spinner icon inside the component. | | group | boolean | false | Enables option grouping. | | optionGroupLabel | string \| null | null | Property name to use as group label. | | optionGroupChildren | string \| null | null | Property name to retrieve children of a group. |

@Output() Events

| Output | Event Payload | Description | | :--- | :--- | :--- | | onChange | { value: any[] } | Callback triggered when selected values change. | | onFilter | { filter: string } | Callback triggered when searching/filtering options. | | onPanelShow | void | Callback triggered when the dropdown overlay opens. | | onPanelHide | void | Callback triggered when the dropdown overlay closes. |

🎨 Custom Templates

Customize option items, header, footer, or selected item chips using structural templates:

<lib-multi-select [options]="countries" [(ngModel)]="selectedCountries" optionLabel="name">
  <!-- Custom Item Template -->
  <ng-template #item let-country>
    <div class="d-flex align-items-center gap-2">
      <span class="flag-icon flag-icon-{{ country.code | lowercase }}"></span>
      <span>{{ country.name }}</span>
    </div>
  </ng-template>

  <!-- Custom Header Template -->
  <ng-template #header>
    <div class="p-2 fw-bold text-muted border-bottom">Select Target Markets</div>
  </ng-template>

  <!-- Custom Footer Template -->
  <ng-template #footer>
    <div class="p-2 text-end text-muted small border-top">Custom Footer</div>
  </ng-template>
</lib-multi-select>

🤝 License & Attribution

This project is open-source software licensed under the MIT License.

It provides a Bootstrap-native port of the MultiSelect component originally designed by PrimeTek.