DEV Community

Cover image for Angular 21 Multiselect Dropdown: A Migration-Friendly Component with Live Functional Tests
Alexandro Paixao Marques
Alexandro Paixao Marques

Posted on

Angular 21 Multiselect Dropdown: A Migration-Friendly Component with Live Functional Tests

#angular #typescript #javascript #npm

Modern Angular applications rarely need just a dropdown.

In real projects, a multiselect dropdown usually sits inside something more important: filters, dashboards, reporting tools, permission editors, workflow screens, admin panels, and data-heavy forms where users need to search, group, select, clear, validate, and keep state consistent.

That is the context behind Stackline Angular Multiselect Dropdown, now available for Angular 21.

This release is not just about making a dropdown compile on the latest Angular version. The goal is to provide a practical component that can be adopted in real applications, tested through live examples, and migrated gradually without forcing teams to rewrite every existing template at once.

Install the package with:

npm install @stackline/angular-multiselect-dropdown
Enter fullscreen mode Exit fullscreen mode

Links:

npm:
https://www.npmjs.com/package/@stackline/angular-multiselect-dropdown

Documentation:
https://alexandro.net/docs/angular/multiselect/angular-21/

Live demo:
https://alexandro.net/docs/angular/multiselect/angular-21/live/?v=21.0.3-20260525-live

GitHub:
https://github.com/alexandroit/angular-multiselect-dropdown

For new releases, documentation updates, and upcoming Angular components, visit:
https://alexandro.net

What the library provides

Stackline Angular Multiselect Dropdown is an Angular multiselect component designed for real application forms, dashboards, filters, and enterprise interfaces.

It supports:

  • single-select and multi-select modes
  • search and filtering
  • select all and clear all behavior
  • grouped options
  • custom item templates
  • custom badge templates
  • template-driven forms
  • reactive forms
  • lazy loading and remote-data hooks
  • CSS and SCSS theming
  • versioned documentation per Angular major
  • modern selector support with legacy selector compatibility

A multiselect component can look simple from the outside, but once it is used across several forms and workflows, replacing it becomes expensive. It affects templates, validation, events, styling, selected state, form reset behavior, and sometimes even backend query logic.

That is why compatibility, predictable APIs, and safe migration paths matter.

Why this package exists

There are many dropdowns and select components available for Angular, but the hard part in real applications is rarely the first implementation.

The hard part is keeping the component stable while Angular moves forward, while forms evolve, while UI layouts become more complex, and while existing screens continue to depend on older selectors or configuration patterns.

This package focuses on a practical set of goals:

  • keep Angular 21 compatibility clear
  • keep the API familiar for existing projects
  • support both template-driven and reactive forms
  • provide working examples that can be tested in the browser
  • preserve a migration path for older templates
  • expose enough configuration for real dashboard and form use cases

The intention is not to reinvent how selection works. The intention is to make a commonly needed UI component easier to adopt, validate, and maintain.

Installation

For Angular 21 projects, install the package with:

npm install @stackline/angular-multiselect-dropdown
Enter fullscreen mode Exit fullscreen mode

Using a dedicated Angular 21 package line helps keep compatibility predictable across local environments, CI pipelines, and production builds.

Module registration

The component is exposed through AngularMultiSelectModule.

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 {}
Enter fullscreen mode Exit fullscreen mode

After registering the module, the component can be used in templates with a data source, selected values, and a settings object.

Basic usage

A typical implementation starts with a list of items, a selected model, and a dropdown configuration.

countries = [
  { id: 1, itemName: 'Brazil' },
  { id: 2, itemName: 'Canada' },
  { id: 3, itemName: 'Portugal' },
  { id: 4, itemName: 'United States' }
];

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

dropdownSettings = {
  singleSelection: false,
  text: 'Select countries',
  selectAllText: 'Select all',
  unSelectAllText: 'Clear all',
  enableCheckAll: true,
  enableSearchFilter: true,
  badgeShowLimit: 4,
  maxHeight: 260,
  showCheckbox: true,
  theme: 'classic',
  primaryKey: 'id',
  labelKey: 'itemName'
};
Enter fullscreen mode Exit fullscreen mode 
<angular-multiselect
  [data]="countries"
  [(ngModel)]="selectedCountries"
  [settings]="dropdownSettings">
</angular-multiselect>
Enter fullscreen mode Exit fullscreen mode

This keeps the template compact while allowing most of the behavior to be configured from TypeScript.

Selector compatibility

The recommended selector for new code is:

<angular-multiselect></angular-multiselect>
Enter fullscreen mode Exit fullscreen mode

The package also keeps support for the older selector:

<angular2-multiselect></angular2-multiselect>
Enter fullscreen mode Exit fullscreen mode

This matters in large Angular applications where selectors may already exist across shared modules, reusable form components, admin screens, internal libraries, and older templates.

Teams can upgrade gradually instead of rewriting everything in one pass. Existing applications can continue working while new development standardizes around the modern selector.

That kind of migration flexibility is important when a UI component is already used in many places.

Forms integration

A production-ready dropdown component must integrate correctly with Angular forms.

The package supports both template-driven forms and reactive forms.

Template-driven forms 

<form #form="ngForm">
  <angular-multiselect
    [data]="countries"
    [(ngModel)]="selectedCountries"
    [settings]="dropdownSettings"
    name="countries"
    required>
  </angular-multiselect>
</form>
Enter fullscreen mode Exit fullscreen mode

Reactive forms 

<form [formGroup]="userForm">
  <angular-multiselect
    [data]="countries"
    [settings]="dropdownSettings"
    formControlName="countries">
  </angular-multiselect>
</form>
Enter fullscreen mode Exit fullscreen mode

In real applications, a multiselect value is not only a visual state. It needs to participate in validation, dirty and touched state, serialization, reset behavior, disabled state, and form submission.

Clean forms integration reduces custom glue code and makes the component easier to maintain across large codebases.

Settings-driven behavior

One of the strongest parts of the package is the settings-driven API.

Most dropdown behavior can be configured through a single settings object instead of requiring wrapper components or repeated template changes.

Supported settings include:

  • singleSelection
  • enableCheckAll
  • enableSearchFilter
  • searchBy
  • maxHeight
  • badgeShowLimit
  • limitSelection
  • disabled
  • searchPlaceholderText
  • groupBy
  • showCheckbox
  • noDataLabel
  • lazyLoading
  • labelKey
  • primaryKey
  • position
  • selectGroup
  • addNewItemOnFilter
  • escapeToClose
  • autoPosition
  • clearAll
  • tagToBody

Single selection without checkboxes 

dropdownSettings = {
  singleSelection: true,
  showCheckbox: false,
  enableCheckAll: false,
  text: 'Select one country'
};
Enter fullscreen mode Exit fullscreen mode

Selection limit 

dropdownSettings = {
  singleSelection: false,
  limitSelection: 2,
  badgeShowLimit: 2,
  text: 'Select up to 2 countries'
};
Enter fullscreen mode Exit fullscreen mode

Grouped data 

countries = [
  { id: 1, itemName: 'Brazil', region: 'South America' },
  { id: 2, itemName: 'Canada', region: 'North America' },
  { id: 3, itemName: 'Portugal', region: 'Europe' }
];

dropdownSettings = {
  groupBy: 'region',
  enableSearchFilter: true,
  text: 'Select countries by region'
};
Enter fullscreen mode Exit fullscreen mode

This approach keeps behavior explicit and discoverable for consumers.

Search and filtering

Search becomes important as soon as datasets grow.

The package supports filtering through enableSearchFilter, while searchBy allows filtering only specific fields.

dropdownSettings = {
  enableSearchFilter: true,
  searchPlaceholderText: 'Search countries',
  searchBy: ['itemName', 'region']
};
Enter fullscreen mode Exit fullscreen mode

This gives teams two useful modes:

  • broad search across item properties
  • controlled search over selected fields

Controlled search is useful when items contain internal IDs, flags, system fields, or hidden metadata that should not match the user input.

For applications with complex objects, predictable search behavior avoids confusing matches and keeps the UI easier to understand.

Custom templates

A multiselect becomes more useful when consumers can control how dropdown items and selected badges are rendered.

Custom item template 

<c-item>
  <ng-template let-item="item">
    <strong>{{ item.itemName }}</strong>
  </ng-template>
</c-item>
Enter fullscreen mode Exit fullscreen mode

Custom badge template 

<c-badge>
  <ng-template let-item="item">
    <span class="country-chip">{{ item.itemName }}</span>
  </ng-template>
</c-badge>
Enter fullscreen mode Exit fullscreen mode

Complete custom template example 

<angular-multiselect
  [data]="countries"
  [(ngModel)]="selectedCountries"
  [settings]="dropdownSettings">

  <c-badge>
    <ng-template let-item="item">
      <span class="country-chip">{{ item.itemName }}</span>
    </ng-template>
  </c-badge>

  <c-item>
    <ng-template let-item="item">
      <strong>{{ item.itemName }}</strong>
      <small>{{ item.region }}</small>
    </ng-template>
  </c-item>

</angular-multiselect>
Enter fullscreen mode Exit fullscreen mode

This is useful when applications need:

  • avatars
  • icons
  • tags
  • role indicators
  • custom layouts
  • region labels
  • permission markers
  • account types
  • status badges

Most business interfaces eventually need more than plain text rendering.

Event system

The component exposes a classic Angular event model for selection workflows.

<angular-multiselect
  [data]="countries"
  [(ngModel)]="selectedCountries"
  [settings]="dropdownSettings"
  (onSelect)="onItemSelect($event)"
  (onDeSelect)="onItemDeSelect($event)"
  (onSelectAll)="onSelectAll($event)"
  (onDeSelectAll)="onDeSelectAll($event)">
</angular-multiselect>
Enter fullscreen mode Exit fullscreen mode

Selection events are useful when dropdown changes need to trigger downstream behavior, such as:

  • refreshing a report
  • loading dependent filters
  • updating query parameters
  • syncing form state
  • sending analytics events
  • enabling related controls
  • validating dependent fields

In many applications, a selection change is not isolated. It is part of a larger workflow. A predictable event contract makes that easier to manage.

Lazy loading and large lists

Large datasets are where simple dropdowns usually start failing.

The package includes lazy loading support and remote-data hooks.

dropdownSettings = {
  text: 'Select items',
  enableSearchFilter: true,
  lazyLoading: true,
  labelKey: 'name',
  primaryKey: 'id',
  maxHeight: 260
};
Enter fullscreen mode Exit fullscreen mode

This matters for applications dealing with:

  • users
  • customers
  • products
  • permissions
  • locations
  • departments
  • catalogs
  • tags
  • reporting dimensions

A component that supports lazy loading can be integrated with local pagination, server-side filtering, remote search workflows, and large-list scenarios.

Dropdown positioning in real layouts

Dropdown positioning problems usually appear only in real layouts.

A dropdown that works on a simple page can behave differently inside:

  • dashboard cards
  • modals
  • side panels
  • scrollable containers
  • constrained widgets
  • table filters
  • embedded panels

The package exposes configuration options such as:

  • position
  • autoPosition
  • tagToBody

These options help keep dropdown behavior stable across complex UI layouts.

Theming strategy

The package ships with bundled CSS and SCSS themes.

A default theme can be added through the Angular styles configuration:

{
  "styles": [
    "node_modules/@stackline/angular-multiselect-dropdown/themes/default.theme.css"
  ]
}
Enter fullscreen mode Exit fullscreen mode

The package also includes:

  • classic theme
  • custom theme
  • dark theme
  • SCSS customization support

This creates two adoption paths.

Fast adoption

Use the bundled CSS theme directly.

{
  "styles": [
    "node_modules/@stackline/angular-multiselect-dropdown/themes/default.theme.css"
  ]
}
Enter fullscreen mode Exit fullscreen mode

Design-system control

Start from the SCSS theme files and adapt styling to the application design system.

{
  "styles": [
    "src/styles.scss",
    "src/styles/multiselect-dropdown.theme.scss"
  ]
}
Enter fullscreen mode Exit fullscreen mode

This gives teams a working default while still allowing deeper customization when the component needs to match an internal design system.

Live functional examples

One of the strongest parts of the Angular 21 release is the live functional documentation.

The Angular 21 documentation includes real interactive examples running in a live Angular environment.

The examples cover:

  1. basic multi-select
  2. search and select all
  3. single selection without checkbox
  4. multi-select without checkbox
  5. selection limits
  6. badge overflow
  7. grouped datasets
  8. disabled states
  9. empty data
  10. long scrollable lists
  11. local lazy loading
  12. custom templates

These examples are not just static documentation. They let developers check the behavior directly in the browser before installing the package.

That matters because UI components are often judged by edge cases: how search behaves, how selected values are displayed, how empty states look, how limits are handled, and how the component reacts in real interaction.

For UI libraries, live examples are part of the trust model.

Angular version strategy

Many Angular libraries use broad peer dependency ranges.

That can look convenient, but it often creates uncertainty. A package may install successfully while still not being clearly validated against the Angular version used in production.

This package follows a stricter strategy where each Angular major receives its own validated package line.

That improves:

  • reproducible builds
  • compatibility validation
  • migration planning
  • CI predictability
  • versioned documentation consistency

For Angular teams, predictable compatibility is often more valuable than optimistic version ranges.

Migration checklist

For teams adopting the Angular 21 line, I would use the following checklist.

1. Install the package 

npm install @stackline/angular-multiselect-dropdown
Enter fullscreen mode Exit fullscreen mode

2. Register the module 

import { AngularMultiSelectModule } from '@stackline/angular-multiselect-dropdown';
Enter fullscreen mode Exit fullscreen mode

3. Add a theme 

{
  "styles": [
    "node_modules/@stackline/angular-multiselect-dropdown/themes/default.theme.css"
  ]
}
Enter fullscreen mode Exit fullscreen mode

4. Use the modern selector for new code 

<angular-multiselect></angular-multiselect>
Enter fullscreen mode Exit fullscreen mode

5. Keep the legacy selector only where needed during migration 

<angular2-multiselect></angular2-multiselect>
Enter fullscreen mode Exit fullscreen mode

6. Verify form behavior

Check:

  • initial selected values
  • reset behavior
  • required validation
  • disabled state
  • reactive form bindings
  • template-driven form bindings

7. Validate real UI scenarios

Test the dropdown inside:

  • modals
  • scrollable containers
  • dashboard cards
  • table filters
  • side panels
  • forms with validation messages

8. Review large-list behavior

For large datasets, evaluate:

  • lazyLoading
  • maxHeight
  • search behavior
  • server-side filtering
  • scroll-to-end handling

9. Standardize settings

Create shared settings presets for your design system.

export const defaultMultiselectSettings = {
  singleSelection: false,
  enableCheckAll: true,
  enableSearchFilter: true,
  badgeShowLimit: 4,
  maxHeight: 260,
  showCheckbox: true,
  theme: 'classic',
  primaryKey: 'id',
  labelKey: 'itemName'
};
Enter fullscreen mode Exit fullscreen mode

This avoids slightly different dropdown behavior across the same application.

When this component is a good fit

This package is a strong fit when you need:

  • Angular 21 compatibility
  • classic Angular module integration
  • template-driven forms support
  • reactive forms support
  • search and select-all behavior
  • grouped options
  • customizable item rendering
  • customizable selected badge rendering
  • theming through CSS and SCSS
  • migration-friendly selector compatibility
  • live examples before adoption
  • bounded Angular major version support

It is especially useful for Angular applications where stability and migration control matter more than replacing every UI control from scratch.

Final thoughts

A good UI component is not only about what appears on the screen.

In real Angular projects, the important questions are practical:

  • Does it integrate cleanly with forms?
  • Does it preserve state correctly?
  • Can teams migrate without rewriting templates?
  • Does it support larger datasets?
  • Can the design system customize it?
  • Are the examples reproducible?
  • Is Angular compatibility clearly validated?

Stackline Angular Multiselect Dropdown for Angular 21 focuses on those concerns.

The package includes search, grouping, select all support, custom templates, form integration, theming, lazy loading, and live Angular 21 examples running in a real application environment.

The migration path is also practical. Existing applications can continue using legacy selectors while newer projects adopt the modern selector progressively.

For teams building or upgrading Angular 21 applications, that combination of compatibility, customization, and validated live examples makes the package a solid option for production use.

For new releases, documentation updates, and upcoming Angular components, visit:

https://alexandro.net

Links

npm:
https://www.npmjs.com/package/@stackline/angular-multiselect-dropdown

Documentation:
https://alexandro.net/docs/angular/multiselect/angular-21/

Live demo:
https://alexandro.net/docs/angular/multiselect/angular-21/live/?v=21.0.3-20260525-live

GitHub:
https://github.com/alexandroit/angular-multiselect-dropdown

Top comments (0)