@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, ADA-compliant keyboard/ARIA support, and support for both template-driven and reactive forms.

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

Latest tested package release: 21.1.2 for Angular 21.x

Credits: Original upstream copyright is preserved in the license. 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 current package release is 21.1.2 for Angular 21.x applications.

The Angular 21 package is compatible with Angular 21.x and was tested in a real Angular 21.2.14 application before npm publication. The 21.1.x line adds ADA-compliant keyboard navigation, focus handling, and ARIA support for the dropdown trigger, clear-all action, selected chips, listbox, and lazy-loaded results. The 21.1.2 patch keeps that behavior, fixes responsive dropdown width handling, and makes tagToBody/appendToBody render the open panel from document.body so dialogs and overflow containers do not clip it.

Features

Table of Contents

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

Rename Note

• new package: @stackline/angular-multiselect-dropdown
• previous package: @stackline/angular2-multiselect-dropdown
• primary selector: <angular-multiselect>
• legacy alias still accepted only for compatibility: <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.

Peer ranges are intentionally bounded to the tested Angular major. The Angular 21 line stays on >=21.0.0 <22.0.0; Angular 22 will receive its own 22.x package line after it is built and validated against Angular 22. Do not treat the Angular 21 package as an open-ended >=21.0.0 dependency.

Installation

npm install @stackline/angular-multiselect-dropdown@21.1.2 --save-exact

Install 21.1.2 for Angular 21.x applications. This line keeps the tested Angular 21 behavior, makes <angular-multiselect> the documented standard selector, keeps <angular2-multiselect> only as a legacy compatibility alias, adds the ADA-compliant keyboard/ARIA accessibility patch, and fixes responsive dropdown width handling.

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: 'Brazil' },
  { id: 2, itemName: 'Canada' },
  { id: 3, itemName: 'Portugal' },
  { id: 4, itemName: 'United States' },
  { id: 5, itemName: 'Argentina' },
  { id: 6, itemName: 'Germany' },
  { id: 7, itemName: 'Japan' },
  { id: 8, itemName: 'South Africa' }
];

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

dropdownSettings = {
  singleSelection: false,
  text: 'Classic basic',
  selectAllText: 'Select all',
  unSelectAllText: 'Clear all',
  enableSearchFilter: true,
  searchPlaceholderText: 'Search',
  badgeShowLimit: 4,
  maxHeight: 260,
  showCheckbox: true,
  noDataLabel: 'No data',
  skin: 'classic',
  tagToBody: false
};

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

Official Angular 21 Test Matrix

The published Angular 21 release was tested in a real Angular 21.2.14 application with @stackline/angular-multiselect-dropdown@21.1.2. The docs now use the same examples from that test app, including the ADA-compliant keyboard, focus, ARIA behavior, and responsive dropdown width handling and body-overlay positioning added in this release line.

Switch between skins through the settings object:

settings = {
  text: 'Classic basic',
  skin: 'classic'
};

materialSettings = {
  text: 'Material basic',
  skin: 'material'
};

settings.theme is still accepted as a legacy alias for older code, but new Angular usage should configure only settings.skin.

The same twelve scenarios are validated for both classic and material:

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>

<angular2-multiselect> remains available only as a legacy compatibility alias for applications migrating from the old outdated plugin. New code and all current examples should use <angular-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.

Dialogs and Overflow Containers

Use tagToBody: true when the dropdown is inside Angular Material dialogs, modals, drawers, or containers that set overflow: hidden or overflow: auto.

settings = {
  text: 'Select countries',
  enableSearchFilter: true,
  skin: 'material',
  tagToBody: true
};

In 21.1.2, tagToBody: true moves the open panel to document.body, keeps it aligned to the original trigger, recalculates position on scroll and resize, and removes the body node on close or destroy. appendToBody: true is also accepted as an alias for teams that prefer that name.

Events

The classic output contract is preserved:

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

Run Locally

npm install
npm run docs:sync

License

MIT