DEV Community: Alexandro Paixao Marques

React Multiselect Dropdown 19: controlled state, skins, modals, and accessibility

Alexandro Paixao Marques — Sat, 30 May 2026 17:30:21 +0000

Modern React 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. It is almost never the feature. It is the control that everything else in the form depends on.

That is the context behind Stackline React Multiselect Dropdown, maintained for React 19.

This is the React counterpart to the Stackline Angular line, and it is meant to behave like one. The two packages share the same combobox and ARIA contract, the same skin system, the same headless philosophy, the same per-major versioning, and the same live-example model. If your organization runs both Angular and React, the goal is that a multiselect feels and behaves the same way in both stacks, instead of being two unrelated controls that happen to share a name. In fact, the combobox contract was first defined and validated in this React line, then carried into the Angular line — so on the React side you are looking at the reference implementation.

React 19 is a good target for that. It is the version where React moved decisively toward explicit async state and less boilerplate: Actions and the new form hooks, the use hook for reading promises and context during render, ref as a plain prop instead of forwardRef, React Server Components as a production pattern, and the React Compiler taking over manual memoization. A maintained, accessibility-focused selection component should slot cleanly into that world without fighting it.

This release of the library is not just about making a dropdown render on the latest React. The goal is a practical component that can be adopted in real applications, exercised through live examples, and customized at whatever depth a team needs — from a drop-in styled component to a fully headless hook where the application owns every element and every line of CSS.

Install the React 19 line with:

npm install @stackline/react-multiselect-dropdown

Links:

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

Documentation (React 19):
https://alexandro.net/docs/react/multiselect/react-19/#/basic

Live demo / interactive playground (StackBlitz):
https://stackblitz.com/github/alexandroit/stackline-react-multiselect-react-19?file=src%2Fexamples%2Fbasic%2Fbasic.component.tsx&startScript=start&initialpath=%2Fbasic

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

For new releases, documentation updates, and the Angular counterpart, visit:
https://alexandro.net

What the library provides

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

It supports:

single-select and multi-select modes
controlled and uncontrolled selection
search and filtering
select all and clear all behavior
grouped options
custom item and badge render functions
a guided Slots API for replacing component structure without losing behavior
headless hooks (useMultiSelectDropdown, useMultiSelectState) for fully custom interfaces
a type-safe factory (createMultiSelectDropdown<T>()) to bind the item type once
imperative ref methods (open, close, focus, select all, clear)
lazy loading hooks and dynamic data
five built-in skins (classic, material, dark, custom, brand)
accessibility-focused keyboard navigation, focus handling, and a documented combobox/ARIA contract
body-overlay positioning for dialogs and clipped containers
versioned documentation per React major

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 state shape, validation, events, styling, selected state, reset behavior, focus and keyboard behavior, and sometimes even backend query logic. The cost is rarely in the first screen. It is in the twentieth screen that quietly depends on the behavior of the first.

That is why a predictable API, accessibility, customization depth, and a clear versioning story matter more than a long feature list.

Why this package exists

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

The hard part is keeping the component stable while React moves forward, while forms evolve, while UI layouts become more complex, while accessibility gets audited, and while a design system needs to take over rendering without rebuilding selection logic from scratch.

React 19 makes that especially relevant. The framework is pushing toward Server Components, form Actions, and the React Compiler, which changes how data arrives and how much manual wiring a component needs. A selection control should be able to live inside that world: take its data from a Server Component or an Action, run as a client component for the parts that genuinely need the browser, and stay out of the way of the compiler.

This package focuses on a practical set of goals:

keep React 19 compatibility clear and validated, not optimistic
keep a controlled, predictable API: data in, selectedItems bound, updates through onChange
offer escalating layers of control, so a team only owns as much markup as it actually needs
ship a documented keyboard and ARIA contract instead of leaving accessibility as an afterthought
provide working examples that can be tested in the browser before installing
keep the same behavior contract as the Angular line, so multi-stack teams get consistency

The intention is not to reinvent how selection works. The intention is to make a commonly needed UI component easy to adopt at any level of customization, and to keep it behaving the same way across React versions and across the Angular counterpart.

React 19 in context

It helps to be explicit about what React 19 changes, because it shapes how any selection component should behave in a 2026 codebase.

Area	Before React 19	React 19
Async/form state	`useState` + `useTransition` + manual pending/error handling	Actions, with `useActionState`, `useFormStatus`, and `useOptimistic`
Reading async data and context	`useEffect` + state; context only via `useContext`	`use()` reads promises and context during render, and can be called conditionally
Refs on function components	`forwardRef` wrapper	`ref` as a regular prop; `forwardRef` no longer required
Server rendering	SSR only	React Server Components as a production pattern, with a `"use client"` boundary
Memoization	manual `useMemo` / `useCallback` / `memo`	React Compiler inserts memoization automatically
Document head	third-party helmet libraries	native metadata hoisting for `<title>`, `<meta>`, `<link>`
Types	`@types/react@18`	`@types/react@19`

There is a clear parallel with where Angular went in the same period. Angular's "signal-first" direction (signals, zoneless change detection, Signal Forms) and React's Actions, use(), and Compiler are different mechanisms aiming at the same outcome: more explicit reactivity, less boilerplate, and rendering that is easier to reason about. That convergence is exactly why a single shared behavior contract across both stacks is worth maintaining.

Where does a styled, controlled multiselect fit in React 19? It is, by nature, a client component. Selection, keyboard handling, focus management, and ARIA state all need the browser, so the component runs under "use client", and that is correct rather than a limitation. The boundary stays clean: a Server Component or an Action can fetch the option list, and the multiselect owns the interaction. For teams that want to push further — fit an RSC-driven design system, drop the bundled CSS, or own every element — the headless hooks provide the selection, filtering, grouping, and ARIA logic without any DOM or CSS, which is the React equivalent of a renderless control.

Installation

For React 19 projects, install the validated 19.x line with an exact version:

npm install @stackline/react-multiselect-dropdown@19.1.1 --save-exact

Pinning with --save-exact keeps compatibility predictable across local environments, CI pipelines, and production builds. The styled component ships its own styles and injects them at runtime; the headless hooks inject no CSS and let your application own the markup and styling.

Unlike the Angular 22 line, which deliberately loosens its peer range to be install-ready for the next framework major, the React 19 line keeps a strict peer range of >=19.0.0 <20.0.0. React's release cadence is slower and less calendar-driven than Angular's, so there is no fixed next-major date to prepare for; bounding the package to the tested React major is the more honest default here. The package was validated against React 19.2.4.

Setup

There is no module to register. React setup is three small steps.

1. Import the component

import { MultiSelectDropdown } from '@stackline/react-multiselect-dropdown';
import type {
  DropdownSettings,
  MultiSelectDropdownHandle
} from '@stackline/react-multiselect-dropdown';

2. Keep selection in React state

const [selectedCountries, setSelectedCountries] = useState<Country[]>([]);

3. Pass a stable settings object

const settings = useMemo<DropdownSettings<Country>>(
  () => ({
    text: 'Select countries',
    enableSearchFilter: true,
    primaryKey: 'id',
    labelKey: 'itemName',
    badgeShowLimit: 3,
    skin: 'classic'
  }),
  []
);

Wrapping the settings object in useMemo keeps its identity stable across renders, which avoids unnecessary work in the component. This is the React analogue of the Angular line's single settings object: most behavior is configured in one place rather than spread across props.

Basic usage

A typical implementation starts with a list of items, selected state, and a settings object.

import { useState, useMemo } from 'react';
import {
  MultiSelectDropdown,
  type DropdownSettings
} from '@stackline/react-multiselect-dropdown';

type Country = {
  id: number;
  itemName: string;
  capital: string;
  region: string;
};

const countries: Country[] = [
  { id: 1, itemName: 'Brazil', capital: 'Brasilia', region: 'South America' },
  { id: 2, itemName: 'Canada', capital: 'Ottawa', region: 'North America' },
  { id: 3, itemName: 'Portugal', capital: 'Lisbon', region: 'Europe' },
  { id: 4, itemName: 'United States', capital: 'Washington, DC', region: 'North America' },
  { id: 5, itemName: 'Argentina', capital: 'Buenos Aires', region: 'South America' },
  { id: 6, itemName: 'Mexico', capital: 'Mexico City', region: 'North America' }
];

export function CountrySelector() {
  const [selectedCountries, setSelectedCountries] = useState<Country[]>([countries[1]]);

  const settings = useMemo<DropdownSettings<Country>>(
    () => ({
      singleSelection: false,
      text: 'Select countries',
      selectAllText: 'Select all',
      unSelectAllText: 'Clear all',
      enableSearchFilter: true,
      searchPlaceholderText: 'Search',
      primaryKey: 'id',
      labelKey: 'itemName',
      badgeShowLimit: 4,
      maxHeight: 260,
      showCheckbox: true,
      noDataLabel: 'No data',
      skin: 'classic',
      appendToBody: false
    }),
    []
  );

  return (
    <MultiSelectDropdown
      data={countries}
      selectedItems={selectedCountries}
      onChange={setSelectedCountries}
      settings={settings}
      onSelect={(item) => console.log('selected', item)}
      onDeSelect={(item) => console.log('removed', item)}
      onSelectAll={(items) => console.log('selected all', items)}
      onDeSelectAll={(items) => console.log('cleared all', items)}
    />
  );
}

The controlled contract is the core idea: you hold the selected array, the component renders from it, and every change comes back through onChange. Note the skin key: the React line selects styling through skin. The older theme key still works as a legacy alias, but new code should use skin.

Customization paths

This is the part where React idioms shine, and it is the React equivalent of "use the right amount of control." Instead of one component with escape hatches, the package exposes escalating layers so a team owns only as much markup as it actually needs.

Layer	Best for	What you own
`<MultiSelectDropdown />`	Fast forms, filters, dashboards, admin screens	Data, selected state, settings, events, optional render functions
`createMultiSelectDropdown<T>()`	Binding the item type once for a feature or design-system wrapper	A typed component family, typed settings, typed slots, typed hooks
`slots`	Custom HTML around proven component behavior	Specific DOM pieces (trigger, badges, menu, search, groups, options, footer)
`useMultiSelectDropdown`	Fully custom interfaces and design systems	All markup and CSS, while the package provides state, ARIA prop getters, keyboard flow, grouping, callbacks
`useMultiSelectState`	Advanced state engines or an existing combobox shell	Every element, every event binding, all visual behavior

For most teams, start with the component. Reach for slots when the component works but your layout needs a different shell. Reach for the headless hooks when the application must own the whole combobox contract. The important point is that selection, filtering, keyboard, focus, ARIA, body-overlay positioning, and async behavior stay handled by the package no matter which layer you choose.

Type-safe factory

Use createMultiSelectDropdown<T>() when a feature, package, or design-system wrapper should bind the item type once and reuse it across the component, settings, slots, and hooks. This is optional; the plain <MultiSelectDropdown /> API remains the fastest path for most screens.

import { useState } from 'react';
import { createMultiSelectDropdown } from '@stackline/react-multiselect-dropdown';

type Country = {
  id: number;
  itemName: string;
  capital: string;
  region: string;
};

const CountryMultiselect = createMultiSelectDropdown<Country>();

const countrySettings = CountryMultiselect.defineSettings({
  text: 'Choose countries',
  primaryKey: 'id',
  labelKey: 'itemName',
  searchBy: ['itemName', 'capital'],
  groupBy: 'region',
  enableSearchFilter: true,
  badgeShowLimit: 2
});

const countrySlots = CountryMultiselect.defineSlots({
  Option: ({ props, option, checkbox }) => (
    <div {...props}>
      {checkbox}
      <strong>{option.item.itemName}</strong>
      <small>{option.item.capital} - {option.item.region}</small>
    </div>
  )
});

export function CountryFilter({ countries }: { countries: Country[] }) {
  const [selectedCountries, setSelectedCountries] = useState<Country[]>([]);

  return (
    <CountryMultiselect.Dropdown
      data={countries}
      selectedItems={selectedCountries}
      onChange={setSelectedCountries}
      settings={countrySettings}
      slots={countrySlots}
    />
  );
}

With the factory, primaryKey, labelKey, searchBy, and groupBy are checked against keyof Country. Typos such as labelKey: 'itemname' or searchBy: ['city'] fail at compile time instead of silently producing an empty search.

Settings-driven behavior

Most behavior is configured through the settings object instead of a long list of props.

Common settings include singleSelection, enableSearchFilter, searchBy, searchPlaceholderText, maxHeight, badgeShowLimit, limitSelection, disabled, groupBy, selectGroup, showCheckbox, noDataLabel, lazyLoading, labelKey, primaryKey, addNewItemOnFilter, clearAll, keyboard, autoPosition, position, skin (legacy alias: theme), appendToBody, and tagToBody.

Single selection without checkboxes

const settings: DropdownSettings<Country> = {
  singleSelection: true,
  showCheckbox: false,
  enableCheckAll: false,
  text: 'Select one country'
};

Selection limit

const settings: DropdownSettings<Country> = {
  singleSelection: false,
  limitSelection: 2,
  badgeShowLimit: 2,
  text: 'Select up to 2 countries'
};

Grouped data

const settings: DropdownSettings<Country> = {
  groupBy: 'region',
  selectGroup: true,
  enableSearchFilter: true,
  text: 'Select countries by region'
};

A single settings object is easy to standardize and share across an application. The most common cause of "the dropdown behaves slightly differently on this screen" is ten slightly different settings objects scattered across ten components; one shared object removes that drift.

Search and filtering

Search becomes important as soon as datasets grow.

enableSearchFilter turns search on, and searchBy restricts filtering to specific fields:

const settings: DropdownSettings<Country> = {
  enableSearchFilter: true,
  searchPlaceholderText: 'Search countries',
  searchBy: ['itemName', 'capital']
};

This gives two useful modes: broad search across item properties, or controlled search over selected fields. Controlled search matters when items carry internal IDs, flags, or hidden metadata that should not match user input — a user typing "12" should not silently match an internal id of 12 unless you decided that on purpose.

Keyboard and accessibility — the combobox contract

This is the part of the React line that deserves the most attention, and it is the reference contract that the Angular line adopted.

Accessibility in a multiselect is a behavior contract, not a single attribute: what the keyboard does on the trigger versus inside the list, how focus moves after a selection, how selected chips are announced, and what screen readers report for each option. Version 19.1.1 tightens the details that usually break first in production forms.

Behavior	Contract
Focus after selection or removal	Focus returns to search while the list stays open, or to the trigger when the list closes
Option selection state	Options expose matching `aria-selected` and `aria-checked` values
Backspace in search	Edits the query; with an empty query it does not remove selected values by default
Backspace/Delete on a focused badge remove button	Removes that selected badge
Escape	Closes the list without clearing selected values
Async add-item	Late async responses are ignored when a newer add request has already resolved
Async option refresh	Selected objects are merged back into the option source, so values are not lost when data refreshes
Keyboard navigation	Trigger ArrowDown/ArrowUp, option Home/End, and stable option ids keep focus and ARIA predictable

Keyboard behavior is enabled by default and configurable through settings.keyboard when an application needs a stricter model:

const settings: DropdownSettings<Country> = {
  text: 'Countries',
  enableSearchFilter: true,
  keyboard: {
    space: true,
    spaceOptionAction: 'toggle',
    tab: true,
    arrows: true,
    escape: true,
    backspaceRemovesLastWhenSearchEmpty: false,
    deleteRemovesFocusedBadge: true
  }
};

Set any key to false to disable that behavior. backspaceRemovesLastWhenSearchEmpty can be turned on for apps that want the legacy "empty search removes last badge" pattern (keyboard.backspace is still accepted as a deprecated alias). spaceOptionAction controls focused options: 'toggle' keeps focus on the current option, while 'toggle-and-next' toggles and advances to the next enabled option. escapeToClose: false is still supported and also disables keyboard.escape.

The edge cases that usually break accessibility — space inside search, tab stealing a selection, escape wiping a form field, a remote refresh dropping the user's selection — were handled deliberately. Because this is the same contract the Angular line follows, the keyboard and screen-reader behavior matches across both stacks.

Custom rendering and the Slots API

There are two levels of visual customization, and they map cleanly to two needs.

Use renderItem and renderBadge when you only need to replace the inner content of an option row or a selected chip:

<MultiSelectDropdown
  data={countries}
  selectedItems={selectedCountries}
  onChange={setSelectedCountries}
  settings={settings}
  renderItem={(item, context) => (
    <span>
      <strong>{context.label}</strong>
      <small>{item.capital}</small>
    </span>
  )}
  renderBadge={(item) => <span>{item.itemName}</span>}
/>

Use the Slots API when you need to replace component structure — the trigger, menu, search shell, option row, badge, footer, and more. The rule is simple: spread the supplied props onto the element that plays that role. Those props carry the required refs, ARIA attributes, keyboard handlers, click handlers, ids, classes, and positioning styles, so you change the markup without losing the tested behavior.

import {
  MultiSelectDropdown,
  type MultiSelectDropdownSlots
} from '@stackline/react-multiselect-dropdown';

const countrySlots: MultiSelectDropdownSlots<Country> = {
  Trigger: ({ props, children, state }) => (
    <div {...props} className={`${props.className} country-trigger`}>
      <span>
        {state.selectedItems.length ? `${state.selectedItems.length} selected` : 'Choose countries'}
      </span>
      {children}
    </div>
  ),
  Badge: ({ props, item, removeButton }) => (
    <span {...props} className={`${props.className} country-badge`}>
      <strong>{item.itemName}</strong>
      {removeButton}
    </span>
  ),
  Option: ({ props, option, checkbox }) => (
    <div {...props} className={`${props.className} country-option`}>
      {checkbox}
      <span>
        <strong>{option.label}</strong>
        <small>{option.item.capital} - {option.item.region}</small>
      </span>
    </div>
  ),
  MenuFooter: ({ props, state }) => (
    <div {...props}>{state.filteredItems.length} visible options</div>
  )
};

The full set of slots covers Root, Trigger, Value, Placeholder, SingleValue, BadgeList, Badge, BadgeLabel, BadgeRemove, Actions, OverflowCounter, ClearAll, Arrow, Menu, Toolbar, BulkActions, SelectAll, AddNewItem, Search, OptionList, Group, GroupHeader, GroupAction, Option, Checkbox, LoadingState, EmptyState, and MenuFooter. This is the React parallel to the Angular line's custom item and badge templates, taken further: in React you can replace almost any structural piece, not just the option and chip.

Headless usage

For the cases where slots are not enough, the package ships headless hooks. This is the React equivalent of the Angular renderless state helper: you write all of the HTML and CSS, and the package gives you state, ARIA prop getters, keyboard flow, grouping, limits, and callbacks.

useMultiSelectDropdown returns prop getters and state for a fully custom interface:

import { useState } from 'react';
import { useMultiSelectDropdown } from '@stackline/react-multiselect-dropdown';

export function HeadlessCountries() {
  const [selectedItems, setSelectedItems] = useState([countries[0]]);

  const dropdown = useMultiSelectDropdown({
    data: countries,
    selectedItems,
    onChange: setSelectedItems,
    settings: {
      text: 'Choose countries',
      enableSearchFilter: true,
      searchPlaceholderText: 'Search country',
      groupBy: 'region',
      primaryKey: 'id',
      labelKey: 'itemName',
      badgeShowLimit: 2,
      clearAll: true
    }
  });

  return (
    <div className="country-picker" {...dropdown.getRootProps()}>
      <button className="country-trigger" {...dropdown.getTriggerProps()}>
        <span>{dropdown.label}</span>
        <strong>{dropdown.isOpen ? 'Close' : 'Open'}</strong>
      </button>

      <div className="country-chips">
        {dropdown.selectedItems.map((item) => (
          <span className="country-chip" key={dropdown.getItemKey(item)}>
            {dropdown.getItemLabel(item)}
            <button {...dropdown.getRemoveButtonProps(item)}>x</button>
          </span>
        ))}
      </div>

      {dropdown.isOpen ? (
        <div className="country-panel" {...dropdown.getListboxProps()}>
          <input className="country-search" {...dropdown.getSearchInputProps()} />
          {dropdown.visibleOptions.map((option) => (
            <div
              key={option.key}
              {...dropdown.getOptionProps(option, {
                className: option.selected ? 'country-option selected' : 'country-option'
              })}>
              <strong>{option.label}</strong>
              <input type="checkbox" checked={option.selected} readOnly />
            </div>
          ))}
        </div>
      ) : null}
    </div>
  );
}

When you want the selection, filtering, and grouping engine without prop getters, use useMultiSelectState:

import { useMultiSelectState } from '@stackline/react-multiselect-dropdown';

const state = useMultiSelectState({
  data: countries,
  selectedItems,
  onChange: setSelectedItems,
  settings: {
    primaryKey: 'id',
    labelKey: 'itemName',
    enableSearchFilter: true
  }
});

The styled component is still available for drop-in usage. The hooks are for teams that want a headless ownership model, including design systems that need to fit React Server Component patterns or drop the bundled CSS entirely.

Forms and controlled state

React does not have ngModel or formControlName; a multiselect participates in a form through controlled state. Keep the selected array in state and derive validity from it:

const [name, setName] = useState('');
const [email, setEmail] = useState('');
const [selectedSkills, setSelectedSkills] = useState<Skill[]>([]);

const formIsValid = email.trim().length > 0 && selectedSkills.length > 0;

return (
  <form onSubmit={(event) => event.preventDefault()}>
    <input value={name} onChange={(event) => setName(event.target.value)} />
    <input value={email} onChange={(event) => setEmail(event.target.value)} />

    <MultiSelectDropdown
      data={skills}
      selectedItems={selectedSkills}
      onChange={setSelectedSkills}
      settings={skillSettings}
    />

    <button type="submit" disabled={!formIsValid}>Submit</button>
  </form>
);

A note on React 19 specifically: the framework's Actions and form hooks (useActionState, useFormStatus, useOptimistic) are now the recommended way to handle async submission. The selected array is plain React state, so it composes naturally with all of them — read selectedItems inside an Action, derive an optimistic update from it, or gate a submit button with useFormStatus. The component does not impose its own form abstraction, which keeps it compatible with whatever submission pattern a screen uses. The docs include both a "template-style forms" example and a "reactive forms" example, named to mirror the Angular line but implemented as ordinary React controlled state.

Events

The package exposes a full set of callbacks for selection workflows:

onChange
onSelect
onDeSelect
onSelectAll
onDeSelectAll
onOpen
onClose
onScrollToEnd
onAddFilterNewItem
onGroupSelect
onGroupDeSelect

Selection events are useful when a change needs to trigger downstream behavior — refreshing a report, loading dependent filters, updating query parameters, sending analytics, enabling related controls, or validating dependent fields. The event names are kept stable across versions, so upgrading the React major does not silently break the handlers you already wrote.

Ref methods

For imperative control, the component exposes a typed handle through ref. In React 19 this works without forwardRef — ref is a normal prop on function components.

const dropdownRef = useRef<MultiSelectDropdownHandle<Country>>(null);

dropdownRef.current?.openDropdown();
dropdownRef.current?.closeDropdown();
dropdownRef.current?.focusSearch();
dropdownRef.current?.selectAll();
dropdownRef.current?.deSelectAll();
dropdownRef.current?.clearSelection();

This is handy for wizard-style flows, "clear filters" buttons elsewhere on the page, or opening the dropdown in response to an external event.

Lazy loading and dynamic data

Large datasets are where simple dropdowns start failing. Enable lazy loading through settings and append more rows when the list reaches the end:

const settings: DropdownSettings<Person> = {
  text: 'Select people',
  enableSearchFilter: true,
  lazyLoading: true,
  labelKey: 'name',
  primaryKey: 'id',
  maxHeight: 140
};

<MultiSelectDropdown
  data={people}
  selectedItems={selectedPeople}
  onChange={setSelectedPeople}
  settings={settings}
  onScrollToEnd={() => setPeople((current) => current.concat(loadMorePeople()))}
/>

This matters for users, customers, products, permissions, locations, departments, catalogs, tags, and reporting dimensions. The docs also include a long-list keyboard-scroll example for large in-memory lists, alongside lazy loading and remote-data examples.

One detail worth calling out for async data: selected objects are preserved across asynchronous refreshes. When a remote call replaces the option list, previously selected items are merged back into the source instead of being silently dropped because the array reference changed. That is exactly the kind of bug that is invisible in a small demo and painful in production, and it is part of the shared contract with the Angular line.

Dialogs and overflow containers

A dropdown that works on a simple page can behave differently inside dialogs, modals, drawers, dashboard cards, table filters, and scrollable containers.

Use appendToBody: true or tagToBody: true when the dropdown sits inside a container that sets overflow: hidden or overflow: auto:

const settings: DropdownSettings<Country> = {
  text: 'Dialog dropdown',
  enableSearchFilter: true,
  skin: 'material',
  appendToBody: true,
  tagToBody: true,
  autoPosition: true
};

With body overlay enabled, the open panel renders against document.body, stays aligned to the original trigger, is sized to the trigger, recalculates on open, scroll, resize, and content changes, and is cleaned up when the dropdown closes or the component unmounts. autoPosition: true treats position as a preferred direction: the menu opens upward only when there is meaningfully less room below and enough room above; otherwise it opens below and shrinks the scrollable list height to stay visible without covering the trigger.

Theming and skins

Styling is selected through settings.skin. The React line ships five built-in skins, which is a superset of the Angular line's classic and material.

Skin	Usage
`classic`	Compact classic dropdown styling
`material`	Material-style rounded controls and chips
`dark`	Dark UI surfaces
`custom`	CSS-variable starter skin for custom projects
`brand`	Stackline brand skin

Switching skins is just a state change:

setSettings((current) => ({ ...current, skin: 'material' }));

settings.theme is accepted as a legacy alias so existing code keeps rendering, but new usage should configure skin. The styled component injects its CSS at runtime; if you want full control, the custom skin is a CSS-variable starting point, and the headless hooks let you drop the bundled CSS entirely and style your own markup.

Live functional examples and StackBlitz playground

The React 19 documentation includes real interactive examples running in a live React environment, and the editable playground is a dedicated React 19 StackBlitz tied to the maintained repository, so it stays in sync with the latest source instead of spawning stale forks per example.

The examples cover, among others:

basic usage
keyboard contract
ARIA state audit
headless + ARIA
state hook
Slots API
type-safe factory
async object preservation
single selection
search filter and search by property
custom search from an API
search and add a new item
grouped options
custom rendering (templating)
template-style and reactive forms
long-list keyboard scroll
lazy loading from an API and remote data
using the control in a list / loop
using the dropdown inside a dialog
multiple dropdowns on one page
dynamic data loading
methods and events
disabled mode, selection limits, badge limits
custom placeholder and styling
body-overlay auto direction

These examples are not just static documentation. They let developers check the behavior directly in the browser before installing — how search behaves, how selected values are displayed, how empty states look, how keyboard navigation feels, and how the component behaves inside a dialog. For UI libraries, live examples are part of the trust model.

Official React 19 test matrix

The React 19 release was validated in a clean React 19.2.4 application using @stackline/react-multiselect-dropdown@19.1.1. The docs reuse the same examples from that test app, including keyboard navigation, focus, ARIA behavior, badge counters, responsive action buttons, scrollable lists, dialog-safe body overlays, the left-aligned and vertically centered placeholder, guided Slots API customization, headless custom HTML, and the combobox contract checks for Backspace, Escape, focused badge removal, focus, and option ARIA.

The same core scenarios are validated across the visual skins.

#	Scenario	Main settings tested
01	Basic multi	`{ enableSearchFilter: true }`
02	All selected badges visible	`{ badgeShowLimit: 10 }`
03	Single selection	`{ singleSelection: true }`
04	Search by fields	`{ searchBy: ['itemName', 'capital'] }`
05	Grouped options	`{ groupBy: 'category', selectGroup: true }`
06	Selection limit	`{ limitSelection: 2, badgeShowLimit: 2 }`
07	Custom rendering	`renderItem` and `renderBadge`
08	Search and add item	`{ addNewItemOnFilter: true }`
09	Disabled state	`{ disabled: true }`
10	Controlled form validation	React state and derived validation
11	Long list with keyboard scroll	`{ maxHeight: 140 }`
12	Local lazy loading	`{ lazyLoading: true }`
13	Dialog and overflow container	`{ appendToBody: true, tagToBody: true }`
14	Body overlay auto direction	`{ autoPosition: true, position: 'top' }`
15	Ref methods	`openDropdown`, `closeDropdown`, `selectAll`, `clearSelection`
16	Slots API custom HTML	`slots.Trigger`, `slots.Option`, `slots.Search`, `slots.GroupHeader`, `slots.MenuFooter`

Publishing the exact scenarios and settings that were tested is a small thing that pays off during adoption: instead of trusting a "tested on React 19" badge, you can see precisely which configurations were exercised, and reproduce them.

React version strategy

Each React major receives its own validated package line, locked to one React family. The compatibility table maps each package family to its React family, its peer range, and the tested release window.

Package family	React family	Peer range	Tested release window
19.x	React 19 only	`>=19.0.0 <20.0.0`	19.1.1 -> 19.2.4
18.x	React 18 only	`>=18.0.0 <19.0.0`	18.0.0 -> 18.3.1
17.x	React 17 only	`>=17.0.0 <18.0.0`	17.0.0 -> 17.0.2

This improves reproducible builds, compatibility validation, migration planning, and versioned-documentation consistency. The ranges are strictly bounded to the tested React major; the React line does not loosen its range the way the Angular 22 line does, because React's slower, less calendar-driven cadence means there is no fixed next-major date to prepare for. For React teams, predictable compatibility is usually more valuable than optimistic version ranges.

Adoption checklist

For teams adopting the React 19 line, I would use the following checklist.

1. Match the package family to your React major

Install the 19.x family for React 19 applications. Keep the package family aligned with the React major your app actually runs.

2. Install the package

npm install @stackline/react-multiselect-dropdown@19.1.1 --save-exact

3. Hold selection in React state

Use useState for the selected array and update it through onChange. Treat the component as fully controlled.

4. Use a stable settings object

Wrap settings in useMemo so its identity stays stable across renders.

5. Choose your customization layer

Start with <MultiSelectDropdown />. Move to slots when the layout needs a different shell, and to the headless hooks when the app must own the whole combobox. Use createMultiSelectDropdown<T>() if a feature or design-system wrapper should bind the item type once.

6. Configure styling through `skin`

Pick from classic, material, dark, custom, or brand. Move any theme usage to skin; theme still works as a legacy alias.

7. Verify keyboard and accessibility

Confirm that space inside search types a space, that tab does not select an option, that escape closes without clearing the field, and that options report consistent aria-selected and aria-checked. Configure settings.keyboard if your app needs different behavior.

8. Validate real UI scenarios

Test inside modals, scrollable containers, dashboard cards, table filters, and forms with validation. Use appendToBody: true (or tagToBody: true) with autoPosition for dialogs and overflow-clipped containers.

9. Review large-list and async behavior

Evaluate lazyLoading, the long-list keyboard-scroll example, maxHeight, onScrollToEnd, server-side filtering, and selected-object preservation across async refreshes.

10. Standardize settings across the app

Create shared settings presets for your design system to avoid slightly different dropdown behavior on different screens.

When this component is a good fit

This package is a strong fit when you need:

React 19 compatibility, validated rather than assumed
a controlled, predictable selection API (data in, selectedItems bound, onChange out)
escalating customization: component, slots, headless hooks, and a typed factory
search, select-all, grouping, and selection limits
a documented keyboard and ARIA combobox contract
custom item and badge rendering, plus structural slots
imperative ref methods for open, close, focus, select all, and clear
five built-in skins and full headless styling control
lazy loading and object preservation for large async lists
live examples and a StackBlitz playground to evaluate before adoption
behavioral consistency with the Stackline Angular line for multi-stack teams

It is especially useful for React applications where predictable selection behavior and accessibility matter, and where a design system wants to own rendering without rebuilding selection logic.

It is probably not the right fit if you want a control built natively around Server Components with no client interactivity. A rich combobox is inherently a client component, and that is correct rather than a limitation. If you want to fit an RSC-heavy design system, the right path is the headless hooks: let a Server Component or an Action provide the data, and use the hook to own the interactive client part. Being clear about that boundary is part of the package being trustworthy.

Final thoughts

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

In real React projects, the important questions are practical: Does it keep selection state predictable? Does it preserve state across async refreshes? Is it accessible by keyboard and to screen readers? Can a design system customize it at the depth it needs? Are the examples reproducible? Is React compatibility clearly validated?

Stackline React Multiselect Dropdown for React 19 focuses on those concerns. The package includes search, grouping, select-all support, custom rendering, a guided Slots API, headless hooks, a typed factory, imperative ref methods, lazy loading, five skins, body-overlay positioning, and live React 19 examples running in a real application environment.

It is also built to be coherent with the Angular line. The combobox and ARIA contract, the skins, the headless philosophy, the per-major versioning, and the live-example model are shared across both ecosystems — with this React line serving as the reference implementation of the shared contract. For teams that run React and Angular side by side, that means a multiselect that behaves the same way in both, which is usually worth more than any single feature.

For new releases, documentation updates, and the Angular counterpart, visit:

https://alexandro.net

Links

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

Documentation (React 19):
https://alexandro.net/docs/react/multiselect/react-19/#/basic

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

All React lines (React 17 to React 19):
https://alexandro.net/docs/react/multiselect/

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

Alexandro Paixao Marques — Mon, 25 May 2026 18:30:45 +0000

Modern Angular applications rarely need just a dropdown.

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

Angular 22 is a meaningful release to target. It landed in early June 2026 as the version where the "signal-first" direction stopped being a roadmap and became the default: zoneless change detection stays the default for new projects, OnPush becomes the default change-detection strategy for new components, Signal Forms graduate to stable, the Angular Aria accessibility primitives are now stable, the toolchain floor moves up to TypeScript 6, and Vitest replaces Karma/Jasmine as the default test runner. A lot of teams will be upgrading specifically to get onto a fresh long-term-support window with that complete feature set.

This release of the library 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, exercised through live examples, and migrated gradually without forcing teams to rewrite every existing template at once — even while the framework underneath them is going through its biggest mental-model shift in years.

Install the Angular 22 line with:

npm install @stackline/angular-multiselect-dropdown

Links:

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

Documentation (Angular 22):
https://alexandro.net/docs/angular/multiselect/angular-22/

Live demo / interactive playground (StackBlitz):
https://stackblitz.com/github/alexandroit/stackline-angular-multiselect-angular-22?startScript=start&initialpath=%2Fbasic

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 with selected and ARIA context
custom badge templates
a renderless state helper for fully custom HTML
template-driven forms
reactive forms
lazy loading, remote-data hooks, and a virtual-scrolling example for very large lists
accessibility-focused keyboard navigation, focus handling, and a documented ARIA contract
CSS and SCSS theming through a skin system
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, focus and keyboard behavior, and sometimes even backend query logic. The cost is rarely in the first screen. It is in the twentieth screen that quietly depends on the behavior of the first.

That is why compatibility, predictable APIs, accessibility, and safe migration paths matter more than a long feature list.

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, while accessibility requirements get audited, and while existing screens continue to depend on older selectors or configuration patterns.

This is especially true right now. Angular 22 is the third release in a deliberate transformation. Signals arrived, zoneless change detection went from preview to default, standalone APIs became the norm, and the framework has been steadily reducing how much RxJS and Zone.js machinery you need for everyday UI state. That progress is good, but it also means a lot of production code is mid-migration: partly modern, partly classic, and very sensitive to anything that forces a rewrite.

This package focuses on a practical set of goals:

keep Angular 22 compatibility clear and validated, not optimistic
keep the API familiar for existing projects so upgrades do not become rewrites
support both template-driven and reactive forms
ship a documented keyboard and ARIA contract instead of leaving accessibility as an afterthought
provide working examples that can be tested in the browser before installing
preserve a migration path for older templates and selectors
expose enough configuration for real dashboard and form use cases, and a renderless mode for the cases that need full control

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 across a framework that is changing quickly underneath it.

Angular 22 in context

It helps to be explicit about what Angular 22 actually changes, because it shapes how any third-party component should behave in a 2026 codebase.

Area	Angular 21	Angular 22
Change detection	Zoneless default for new projects	Zoneless default; `OnPush` is the default strategy for new components
Forms	Signal Forms introduced as experimental	Signal Forms stable and production-ready
Accessibility	Angular Aria in developer preview	Angular Aria primitives stable
Components	Standalone the norm	Selectorless components (import directly in templates) maturing
TypeScript	5.x supported	TypeScript 6 required; 5.9 and older dropped
Testing	Vitest opt-in	Vitest as the default, faster test runner
Tooling	MCP server support	MCP/AI tooling stabilized

The takeaway is that most of what the Angular 21 notes described as "coming" or "try this" is now the recommended path. The framework is firmly signal-first, but it is also explicit that this is progressive modernization rather than a forced rewrite — signals coexist with RxJS, and Zone.js is still supported for existing apps.

Where does a classic settings-driven multiselect fit in that world? Honestly, it is not a signal-native control, and this is a deliberate design choice rather than an oversight. Enterprise Angular codebases still contain large amounts of NgModule-based composition and template-driven or reactive forms that work perfectly well and are not getting rewritten just because OnPush is now a default. This package leans into that: it ships as an NgModule with the classic API on purpose, so a team can move its build to Angular 22 without simultaneously rewriting every form that touches the dropdown. For the cases that do want a fully modern, custom surface, the renderless state helper (covered below) lets you own the rendering and wiring while the library handles selection, item identity, filtering, object preservation, and ARIA state.

Installation

For Angular 22 projects, install the validated 22.x line with an exact version:

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

Pinning the version with --save-exact keeps compatibility predictable across local environments, CI pipelines, and production builds. The 22.0.1 patch keeps the tested Angular 22 behavior, makes <angular-multiselect> the documented standard selector, keeps <angular2-multiselect> only as a legacy compatibility alias, and ships the accessibility and keyboard/ARIA interaction contract.

There is one intentional exception to the usual strict peer ranges. The Angular 22 line uses >=22.0.0 <24.0.0 instead of bounding only to Angular 22. That lets Angular 23 projects install the package on launch day while the dedicated Angular 23 validation line is being prepared, without weakening the compatibility story for everyone else. The package was tested in a real Angular 22.0.0 application before publication.

Module registration

The component is exposed through AngularMultiSelectModule.

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 {}

Angular 22 does not force you off NgModules. The framework keeps backward compatibility, and module-based registration is still a first-class way to compose an application. Registering this module remains the supported path, and it is also what makes the component drop cleanly into existing module-based screens that you are not planning to convert to standalone right now. 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,
  searchPlaceholderText: 'Search',
  badgeShowLimit: 4,
  maxHeight: 260,
  showCheckbox: true,
  noDataLabel: 'No data',
  skin: 'classic',
  primaryKey: 'id',
  labelKey: 'itemName',
  tagToBody: false
};

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

This keeps the template compact while allowing most of the behavior to be configured from TypeScript. Note the skin key: in the Angular 22 line, styling is selected through skin (classic or material). The older theme key is still accepted as a legacy alias for existing code, but new usage should configure skin.

Selector compatibility

The recommended selector for new code is:

<angular-multiselect></angular-multiselect>

The package also keeps support for the older selector:

<angular2-multiselect></angular2-multiselect>

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 exactly what you want during an Angular 22 upgrade, where the framework change itself is already enough work without dragging every component rename into the same pull request.

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
searchPlaceholderText
searchAutofocus
maxHeight
badgeShowLimit
limitSelection
disabled
groupBy
selectGroup
showCheckbox
noDataLabel
lazyLoading
labelKey
primaryKey
ariaLabel
keyboard
position
autoPosition
addNewItemOnFilter
escapeToClose
clearAll
skin (legacy alias: theme)
tagToBody (alias: appendToBody)

Single selection without checkboxes

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

Selection limit

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

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'
};

This approach keeps behavior explicit and discoverable for consumers. A single settings object is also easy to standardize and share across an application, which matters more than it sounds: the most common cause of "the dropdown behaves slightly differently on this screen" is ten slightly different settings objects scattered across ten components.

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']
};

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 — a user typing "12" should not silently match an internal id of 12 unless you decided that on purpose.

Keyboard and accessibility

This is the part of the Angular 22 line that deserves the most attention, and it lines up directly with Angular Aria becoming stable in the framework.

Accessibility in a multiselect is not a single attribute. It is a behavior contract: what the keyboard does on the trigger versus inside the list, how focus moves, how selected chips are announced, and what screen readers report for each option. The package exposes that contract through a keyboard settings object so you can configure it instead of fighting it.

dropdownSettings = {
  text: 'Keyboard-tested countries',
  enableSearchFilter: true,
  searchAutofocus: false,
  keyboard: {
    space: true,
    spaceOptionAction: 'toggle',
    tab: true,
    arrows: true,
    escape: true,
    backspaceRemovesLastWhenSearchEmpty: false,
    deleteRemovesFocusedBadge: true
  }
};

The default behavior is designed to match what users expect from a real combobox:

Space on the trigger opens or closes the dropdown.
Space on an option toggles that option and keeps focus on it.
Search inputs type a normal space, so searching is never hijacked by selection logic.
Tab moves focus and never accidentally selects an option.
Escape closes the list without clearing the selected values.
Empty-search Backspace does not remove selected values by default, which prevents accidental data loss.
A focused badge or remove button can be removed intentionally with Backspace or Delete.
Options expose matching aria-selected and aria-checked values, so assistive technology reports a consistent state.

The Angular line follows the same combobox contract that was validated in the related React 19.1.x work, then exposed through Angular settings. Carrying one tested interaction model across both frameworks means the behavior is not reinvented per platform, and the edge cases that usually break accessibility — space inside search, tab stealing a selection, escape wiping a form field — were handled deliberately rather than by accident.

Custom templates

A multiselect becomes more useful when consumers can control how dropdown items and selected badges are rendered. In the Angular 22 line, the item template context is richer: alongside item, you also receive label, selected, and ariaChecked, so custom rendering can reflect selection and accessibility state without you recomputing it.

Custom item template

<c-item>
  <ng-template
    let-item="item"
    let-label="label"
    let-selected="selected"
    let-ariaChecked="ariaChecked">
    <span [attr.data-aria-checked]="ariaChecked">
      {{ label }}
      <strong *ngIf="selected">Selected</strong>
    </span>
  </ng-template>
</c-item>

Custom badge template

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

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"
      let-label="label"
      let-selected="selected"
      let-ariaChecked="ariaChecked">
      <strong>{{ label }}</strong>
      <small>{{ item.region }}</small>
    </ng-template>
  </c-item>

</angular-multiselect>

This is useful when applications need avatars, icons, tags, role indicators, custom layouts, region labels, permission markers, account types, or status badges. Most business interfaces eventually need more than plain text rendering, and exposing selected and ariaChecked in the template context means the visual state and the accessible state stay in sync instead of drifting apart.

Renderless state helper

For the cases where settings and templates are not enough, the Angular 22 line ships a renderless (headless) state helper. This is the part that fits the signal-first, "own your rendering" direction of modern Angular: you write all of the HTML, and the library gives you selection, filtering, item identity, object preservation, and ARIA state.

Use AngularMultiselectState when you want Stackline behavior under fully custom markup:

import {
  AngularMultiselectState,
  defineAngularMultiselectSettings
} from '@stackline/angular-multiselect-dropdown';

interface CountryOption {
  id: number;
  itemName: string;
  region: string;
}

state = new AngularMultiselectState<CountryOption>({
  data: countries,
  selectedItems: [countries[0]],
  settings: defineAngularMultiselectSettings<CountryOption>({
    primaryKey: 'id',
    labelKey: 'itemName',
    searchBy: ['itemName', 'region'],
    ariaLabel: 'Headless country picker'
  }),
  onChange: (items) => {
    selectedItems = items;
  }
});

The documentation includes a dedicated headless and ARIA route that binds the returned trigger, listbox, and option state into fully custom Angular HTML. Practically, this lets a design system build its own visual component on top of a tested selection engine, instead of either fighting the default rendering or rebuilding selection logic from scratch.

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>

Reactive forms

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

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.

A word on Angular 22 specifically: Signal Forms are now stable, and many new projects will reach for them. The Angular team has been explicit that forms interoperability is a priority and that the reactive and template-driven systems are not going away. This component integrates through the classic ControlValueAccessor path, which keeps it working inside existing template-driven and reactive forms during a migration. If a screen is rebuilt around Signal Forms, the renderless state helper is the cleaner bridge, because it hands you the selected items through onChange and lets you drive a signal yourself. Clean forms integration reduces custom glue code and keeps the component maintainable across large codebases that are part-modern, part-classic.

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)"
  (onAddFilterNewItem)="onAddNewItem($event)">
</angular-multiselect>

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, or validating dependent fields.

In many applications, a selection change is not isolated. It is part of a larger workflow. A predictable, stable event contract makes that easier to manage — and keeping the same output names across versions means the upgrade to Angular 22 does not silently break the handlers you already wrote.

Lazy loading, virtual scrolling, 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
};

This matters for applications dealing with users, customers, products, permissions, locations, departments, catalogs, tags, or reporting dimensions. A component that supports lazy loading can be integrated with local pagination, server-side filtering, remote search workflows, and large-list scenarios.

The Angular 22 documentation also adds a dedicated virtual-scrolling example for very large option sets, alongside the lazy-loading and remote-data examples. The distinction is worth understanding: lazy loading is about fetching more data as the user scrolls or searches, while virtual scrolling is about rendering only the visible rows of a list that is already in memory. Large enterprise lists often need both — fetch in pages, render a window — and having a working example for each keeps you from guessing which problem you actually have.

One important detail for async data: the Angular 22 line preserves the selected objects across asynchronous refreshes. When a remote call replaces the option list, previously selected items are not silently dropped just because the array reference changed. That is exactly the kind of bug that is invisible in a small demo and painful in production.

Dialogs and overflow containers

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, and embedded panels.

The package exposes configuration options such as position, autoPosition, and tagToBody (also accepted as appendToBody).

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.

Use tagToBody: true when the dropdown is inside Angular Material dialogs, modals, drawers, or any container that sets overflow: hidden or overflow: auto:

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

With tagToBody: true, the open panel renders outside the clipping container, stays aligned to the original trigger, keeps the menu surface opaque, recalculates position on scroll and resize, and cleans itself up on close or destroy. The opaque-surface and dialog-safe positioning behavior is carried forward from the Angular 21.2.x baseline, so the upgrade does not regress the hard-won layout fixes.

Theming strategy

The package ships with bundled CSS and SCSS, and styling is selected through the skin setting (classic or material). skin replaces the older theme key; theme still works as a legacy alias so existing code keeps rendering.

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

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

The package also ships a full custom starter theme in both formats, so there are two adoption paths.

Fast adoption

Use the bundled CSS theme directly.

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

Design-system control

Start from the SCSS theme file, keep it in your application source, and adapt the selectors and tokens to your design system.

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

Switching skins at runtime is just a settings change:

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

This gives teams a working default while still allowing deeper customization when the component needs to match an internal design system. The css starter is for teams that want a plain compiled file they can copy and adjust without a Sass pipeline; the scss starter is for teams that want to take over the component styling completely.

Live functional examples and StackBlitz playground

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

The Angular 22 documentation includes real interactive examples running in a live Angular environment, and the editable playground is a single Angular 22 StackBlitz with isolated lazy routes. The official links use stackblitz.com/github against the maintained GitHub repository, so they stay tied to the latest pushed source instead of creating stale forked copies for every example. Each example has its own folder, Angular module, data object, and URL.

The Angular 22 examples cover:

basic multi-select
single selection
search and select all
custom search from an API
search filter by property
search and add a new item
grouped datasets
custom item and badge templating
template-driven forms
reactive forms
virtual scrolling
lazy loading from an API
remote data
using the control in a list / for loop
using the dropdown inside a dialog
multiple dropdowns on one page
dynamic data loading
component methods
events
disabled mode
selection limits
badge overflow limits
custom placeholder and styling

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 usually judged by edge cases: how search behaves, how selected values are displayed, how empty states look, how limits are handled, how keyboard navigation feels, and how the component reacts in real interaction. For UI libraries, live examples are part of the trust model.

Official Angular 22 test matrix

The Angular 22 release was validated in a real Angular 22.0.0 application using @stackline/angular-multiselect-dropdown@22.0.1. The documentation reuses the same example pattern from that clean test app, including the accessibility-focused keyboard, focus, and ARIA behavior, responsive dropdown width handling, opaque menu surfaces, and dialog-safe positioning carried forward from the Angular 21.2.x line.

The same twelve scenarios are validated for both the classic and material skins.

#	Scenario	Main settings tested
01	Basic multi	`{ enableSearchFilter: false }`
02	Search + select all	search, select all, clear all, events
03	Single without checkbox	`{ singleSelection: true, showCheckbox: false, enableCheckAll: false }`
04	Multi without checkbox	`{ showCheckbox: false, enableCheckAll: false }`
05	Selection limit	`{ limitSelection: 2, badgeShowLimit: 2 }`
06	Badge overflow	`{ badgeShowLimit: 2, maxHeight: 220 }`
07	Grouped by region	`{ groupBy: 'region', maxHeight: 220 }`
08	Disabled with value	`{ disabled: true }`
09	Empty data	`{ noDataLabel: 'No records found' }`
10	Long list with scroll	`{ maxHeight: 120, badgeShowLimit: 3 }`
11	Local lazy loading	`{ lazyLoading: true, maxHeight: 120, badgeShowLimit: 3 }`
12	Item + chip template	`<c-badge>` and `<c-item>` custom templates

Publishing the exact scenarios and settings that were tested is a small thing that pays off during adoption: instead of trusting a "tested on Angular 22" badge, you can see precisely which configurations were exercised, and reproduce them.

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, locked to one framework major. The compatibility table in the repository maps each package family to its Angular family, its peer range, and the tested release window — all the way back from Angular 22 to Angular 2.

That improves reproducible builds, compatibility validation, migration planning, CI predictability, and versioned-documentation consistency.

The Angular 22 line is the one deliberate exception. Its peer range is >=22.0.0 <24.0.0 rather than being bounded to Angular 22 alone, so Angular 23 projects can install it on launch day while the dedicated Angular 23 validation line is prepared. Angular 21 stays bounded at >=21.0.0 <22.0.0. The point is to give Angular 23 early adopters a working install path without pretending the package has already been validated against a framework version that may not have shipped yet.

For Angular teams, predictable compatibility is usually more valuable than optimistic version ranges, and being explicit about the one place the range is loosened is part of keeping that trust.

Migration checklist

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

1. Get onto a supported Angular version first

Angular follows an 18-month lifecycle (6 months active support, 12 months LTS). Angular 19 reached end-of-life on May 19, 2026, and everything below Angular 20 is unsupported. Separate the framework upgrade from pattern modernization: reach Angular 22 first, then adopt signals, Signal Forms, and selectorless components incrementally.

2. Install the package

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

3. Register the module

import { AngularMultiSelectModule } from '@stackline/angular-multiselect-dropdown';

4. Add a theme

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

5. Move `theme` to `skin`

Update settings objects to use skin: 'classic' or skin: 'material'. Leave theme only where you have not migrated yet, since it still works as a legacy alias.

6. Use the modern selector for new code

<angular-multiselect></angular-multiselect>

7. Keep the legacy selector only where needed during migration

<angular2-multiselect></angular2-multiselect>

8. Verify form behavior

Check initial selected values, reset behavior, required validation, disabled state, reactive form bindings, and template-driven form bindings. If a screen is being rebuilt on Signal Forms, plan to bridge through the renderless state helper.

9. Verify keyboard and accessibility

Confirm that space inside the search input types a space, that tab does not select an option, that escape closes without clearing the field, and that options report consistent aria-selected and aria-checked. Configure the keyboard settings object if your application needs different behavior.

10. Validate real UI scenarios

Test the dropdown inside modals, scrollable containers, dashboard cards, table filters, side panels, and forms with validation messages. Use tagToBody: true (or appendToBody: true) for dialogs and overflow-clipped containers.

11. Review large-list behavior

For large datasets, evaluate lazyLoading, virtual scrolling, maxHeight, search behavior, server-side filtering, scroll-to-end handling, and selected-object preservation across async refreshes.

12. 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,
  skin: 'classic',
  primaryKey: 'id',
  labelKey: 'itemName'
};

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 22 compatibility, validated rather than assumed
classic Angular module integration that drops into existing NgModule screens
template-driven and reactive forms support during a migration
search, select-all, grouping, and selection limits
a documented keyboard and ARIA contract, aligned with Angular Aria
customizable item and badge rendering, with selected and ARIA context in the template
a renderless mode for fully custom HTML on top of a tested selection engine
theming through CSS and SCSS via a skin system
migration-friendly selector compatibility
lazy loading, virtual scrolling, and object preservation for large async lists
live examples and a StackBlitz playground to evaluate before adoption
bounded, per-major Angular version support

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

It is probably not the right choice if you are starting a brand-new, fully signal-first application with no legacy forms and you want a component built natively around signals and selectorless composition. In that case, either use the renderless state helper as the foundation and build your own surface on top of it, or pick a signal-native control. Being clear about that boundary is part of the package being trustworthy: it is optimized for continuity, not for being the most modern thing on the page.

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 across async refreshes? Is it accessible by keyboard and to screen readers? Can teams migrate without rewriting templates? Does it handle larger datasets? Can the design system customize it? Are the examples reproducible? Is Angular compatibility clearly validated?

Stackline Angular Multiselect Dropdown for Angular 22 focuses on those concerns. The package includes search, grouping, select-all support, custom templates, a documented keyboard and ARIA contract, a renderless state helper, form integration, theming through skins, lazy loading and virtual scrolling, and live Angular 22 examples running in a real application environment.

The migration path is also practical. Existing applications can keep their NgModule registration, classic API, and legacy selectors while newer projects adopt the modern selector and renderless mode progressively — which is exactly the posture Angular 22 itself takes toward modernization. For teams building or upgrading Angular 22 applications during the signal-first transition, that combination of validated compatibility, accessibility, customization, and reproducible 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 (Angular 22):
https://alexandro.net/docs/angular/multiselect/angular-22/

Live demo / interactive playground (StackBlitz):
https://stackblitz.com/github/alexandroit/stackline-angular-multiselect-angular-22?startScript=start&initialpath=%2Fbasic

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

All Angular lines (Angular 2 to Angular 22):
https://alexandro.net/docs/angular/multiselect/

DEV Community: Alexandro Paixao Marques

React Multiselect Dropdown 19: controlled state, skins, modals, and accessibility

What the library provides

Why this package exists

React 19 in context

Installation

Setup

1. Import the component

2. Keep selection in React state

3. Pass a stable settings object

Basic usage

Customization paths

Type-safe factory

Settings-driven behavior

Single selection without checkboxes

Selection limit

Grouped data

Search and filtering

Keyboard and accessibility — the combobox contract

Custom rendering and the Slots API

Headless usage

Forms and controlled state

Events

Ref methods

Lazy loading and dynamic data

Dialogs and overflow containers

Theming and skins

Live functional examples and StackBlitz playground

Official React 19 test matrix

React version strategy

Adoption checklist

1. Match the package family to your React major

2. Install the package

3. Hold selection in React state

4. Use a stable settings object

5. Choose your customization layer

6. Configure styling through skin

7. Verify keyboard and accessibility

8. Validate real UI scenarios

9. Review large-list and async behavior

10. Standardize settings across the app

When this component is a good fit

Final thoughts

Links

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

What the library provides

Why this package exists

Angular 22 in context

Installation

Module registration

Basic usage

Selector compatibility

Settings-driven behavior

Single selection without checkboxes

Selection limit

Grouped data

Search and filtering

Keyboard and accessibility

Custom templates

Custom item template

Custom badge template

Complete custom template example

Renderless state helper

Forms integration

Template-driven forms

Reactive forms

Event system

Lazy loading, virtual scrolling, and large lists

Dialogs and overflow containers

Theming strategy

Fast adoption

Design-system control

Live functional examples and StackBlitz playground

Official Angular 22 test matrix

Angular version strategy

Migration checklist

1. Get onto a supported Angular version first

2. Install the package

3. Register the module

4. Add a theme

6. Configure styling through `skin`

5. Move `theme` to `skin`