@stackline/angular-multiselect-dropdown

A maintained Angular multiselect dropdown for classic Angular forms workflows, with search, grouping, custom item and badge templates, lazy loading, custom CSS/SCSS theming, and support for both template-driven and reactive forms.

Documentation & Live Demos | Angular 21 Demo | npm | Issues | Repository

Latest version: 21.0.1

---

Credits: Original library by Cuppa Labs. Current maintenance, Angular line stewardship, publishing, and documentation by Alexandro Paixao Marques.

---

Why this library?

The original angular2-multiselect-dropdown package became difficult to keep current across multiple Angular generations. This maintained package keeps the classic API and template structure intact, introduces the new primary selector <angular-multiselect>, preserves the legacy alias <angular2-multiselect>, and publishes the project line by line so older applications can keep a predictable upgrade path.

The repository contains the full documentation matrix from Angular 2 through Angular 21. The npm rollout is complete line by line, and 21.0.1 is the current latest published line for Angular 21 applications.

Features

Feature	Supported
Angular 21 latest published release line	✅
Multi-select and single-select modes	✅
Search and filter	✅
Group by field	✅
Custom item templates (<c-item>)	✅
Custom badge templates (<c-badge>)	✅
Template-driven forms (ngModel)	✅
Reactive forms (formControlName)	✅
Lazy loading and remote-data hooks	✅
Theming via bundled CSS/SCSS	✅
Primary selector <angular-multiselect>	✅
Legacy selector <angular2-multiselect>	✅
Versioned docs builds per Angular line	✅

Table of Contents

1. Rename Note
2. Angular Version Compatibility
3. Installation
4. Setup
5. Custom CSS and SCSS Themes
6. Basic Usage
7. Custom Templates
8. Forms Integration
9. Lazy Loading and Remote Data
10. Events
11. Run Locally
12. License

Rename Note

• new package: @stackline/angular-multiselect-dropdown
• previous package: @stackline/angular2-multiselect-dropdown
• primary selector: <angular-multiselect>
• legacy alias still accepted: <angular2-multiselect>

Angular Version Compatibility

Each package family only installs on its matching Angular family. Framework major and package major are not always the same package number, so use the package family column below.

Package family	Framework family	Peer range	Tested release window	Demo link
21.x	Angular 21 only	>=21.0.0 <22.0.0	21.0.0 -> 21.2.8	Angular 21 family docs
20.x	Angular 20 only	>=20.0.0 <21.0.0	20.0.0 -> 20.3.18	Angular 20 family docs
19.x	Angular 19 only	>=19.0.0 <20.0.0	19.0.0 -> 19.2.20	Angular 19 family docs
18.x	Angular 18 only	>=18.0.0 <19.0.0	18.0.0 -> 18.2.14	Angular 18 family docs
17.x	Angular 17 only	>=17.0.0 <18.0.0	17.0.0 -> 17.3.12	Angular 17 family docs
16.x	Angular 16 only	>=16.0.0 <17.0.0	16.0.0 -> 16.2.12	Angular 16 family docs
15.x	Angular 15 only	>=15.0.0 <16.0.0	15.0.0 -> 15.2.10	Angular 15 family docs
14.x	Angular 14 only	>=14.0.0 <15.0.0	14.0.0 -> 14.3.0	Angular 14 family docs
13.x	Angular 13 only	>=13.0.0 <14.0.0	13.0.0 -> 13.4.0	Angular 13 family docs
12.x	Angular 12 only	>=12.0.0 <13.0.0	12.0.0 -> 12.2.17	Angular 12 family docs
11.x	Angular 11 only	>=11.0.0 <12.0.0	11.0.0 -> 11.2.14	Angular 11 family docs
10.x	Angular 10 only	>=10.0.0 <11.0.0	10.0.0 -> 10.2.5	Angular 10 family docs
9.x	Angular 9 only	>=9.0.0 <10.0.0	9.0.0 -> 9.1.13	Angular 9 family docs
8.x	Angular 8 only	>=8.0.0 <9.0.0	8.0.0 -> 8.2.14	Angular 8 family docs
7.x	Angular 7 only	>=7.0.0 <8.0.0	7.0.0 -> 7.2.16	Angular 7 family docs
6.x	Angular 6 only	>=6.0.0 <7.0.0	6.0.0 -> 6.1.10	Angular 6 family docs
5.x	Angular 5 only	>=5.0.0 <6.0.0	5.0.0 -> 5.2.11	Angular 5 family docs
4.x	Angular 4 only	>=4.0.0 <5.0.0	4.0.0 -> 4.4.7	Angular 4 family docs
2.x	Angular 2 only	>=2.0.0 <3.0.0	2.0.0 -> 2.4.10	Angular 2 family docs

Installation

npm install @stackline/angular-multiselect-dropdown

Choose the package family from the compatibility table above. Each published family is locked to one framework major only.

Setup

1. Import the module

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { FormsModule } from '@angular/forms';
import { AngularMultiSelectModule } from '@stackline/angular-multiselect-dropdown';

@NgModule({
  imports: [
    BrowserModule,
    FormsModule,
    AngularMultiSelectModule
  ]
})
export class AppModule {}

2. Add the default theme

"styles": [
  "node_modules/@stackline/angular-multiselect-dropdown/themes/default.theme.css"
]

Custom CSS and SCSS Themes

The package also ships a full custom starter theme in both formats:

• node_modules/@stackline/angular-multiselect-dropdown/themes/custom.theme.scss
• node_modules/@stackline/angular-multiselect-dropdown/themes/custom.theme.css

Use the scss file when you want to take over the component styles completely and keep the theme in your app source:

"styles": [
  "src/styles.scss",
  "src/styles/multiselect-dropdown.theme.scss"
]

Start src/styles/multiselect-dropdown.theme.scss from the package file above and edit the selectors and tokens freely.

Use the css file when you want a plain compiled starter that can be copied and adjusted without a Sass pipeline.

Basic Usage

dropdownList = [
  { id: 1, itemName: 'India' },
  { id: 2, itemName: 'Singapore' },
  { id: 3, itemName: 'Australia' },
  { id: 4, itemName: 'Canada' }
];

selectedItems = [{ id: 2, itemName: 'Singapore' }];

dropdownSettings = {
  singleSelection: false,
  text: 'Select Countries',
  selectAllText: 'Select All',
  unSelectAllText: 'UnSelect All',
  enableSearchFilter: true,
  tagToBody: false
};

<angular-multiselect
  [data]="dropdownList"
  [(ngModel)]="selectedItems"
  [settings]="dropdownSettings"
  (onSelect)="onItemSelect($event)"
  (onDeSelect)="onItemDeSelect($event)"
  (onSelectAll)="onSelectAll($event)"
  (onDeSelectAll)="onDeSelectAll($event)">
</angular-multiselect>

Custom Templates

<angular-multiselect
  [data]="dropdownList"
  [(ngModel)]="selectedItems"
  [settings]="dropdownSettings">
  <c-item>
    <ng-template let-item="item">
      <label>{{ item.itemName }}</label>
      <img [src]="item.image" style="width: 24px; margin-left: 8px;" />
    </ng-template>
  </c-item>
</angular-multiselect>

The same template contract also works with the legacy selector:

<angular2-multiselect></angular2-multiselect>

Forms Integration

Template-driven forms

<form #form="ngForm">
  <angular-multiselect
    [data]="skills"
    [(ngModel)]="selectedSkills"
    [settings]="settings"
    name="skills"
    required>
  </angular-multiselect>
</form>

Reactive forms

<form [formGroup]="userForm">
  <angular-multiselect
    [data]="skills"
    [settings]="settings"
    formControlName="skills">
  </angular-multiselect>
</form>

Lazy Loading and Remote Data

Enable lazy loading through the settings object and respond to the scroll event from your container logic:

settings = {
  text: 'Select Items',
  enableSearchFilter: true,
  lazyLoading: true,
  labelKey: 'name',
  primaryKey: 'id'
};

The versioned docs include working examples for lazy loading, remote data, grouping, templating, and forms usage.

For sticky cards, constrained containers, or dashboard layouts, keep tagToBody: false so the dropdown panel stays anchored to the field and does not jump across the page.

Events

The classic output contract is preserved:

• (onSelect)
• (onDeSelect)
• (onSelectAll)
• (onDeSelectAll)
• (onAddFilterNewItem)

Run Locally

npm install
npm run docs:sync
npm run build-package
cd docs-src/angular-21
npm install --ignore-scripts
npm run build

License

MIT