ComboboxMulti

v0.3.4

Documentation Under Review

Catalyst ComboboxMulti combines a text input with a Radix UI Popover to deliver a fully accessible multi-select dropdown — with tag display for selected items, search filtering, keyboard navigation, and design-token styling out of the box.

Installation

npm install @pmi/catalyst-combobox-multi

import {
  ComboboxMultiTrigger,
  ComboboxMultiItem,
  ComboboxMultiSeparator,
  ComboboxMultiScrollButton,
} from '@pmi/catalyst-combobox-multi';

Variants

Default

A standard multi-select combobox with tag display and search filtering.

Danger

Use the danger variant to indicate validation errors or destructive selections.

Disabled

Use the disabled variant to prevent interaction with the trigger and its options.

Sizes

ComboboxMultiTrigger supports three sizes via the size prop: sm, md (default), and lg.

Common Patterns

With Badges

Display badges alongside options for additional context such as category or count.

With Scroll Buttons

Add ComboboxMultiScrollButton above and below the options list to scroll long lists with a pointer. The list also scrolls natively.

API Reference

ComboboxMulti is a compound component. The sections below summarize the Catalyst-specific API surface for each part.

ComboboxMultiTrigger

The button that opens the dropdown and displays selected items as tags.

Extends HTMLAttributes<HTMLDivElement>.

ComboboxMultiItem

An individual selectable option with checkbox indicator.

Extends HTMLAttributes<HTMLDivElement>.

ComboboxMultiSeparator

A visual divider between the search input and the options list.

ComboboxMultiScrollButton

Scroll control buttons (up/down) for long option lists.

Accessibility

ComboboxMulti is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

ARIA

• role="combobox" — applied to the trigger and search input
• role="listbox" — applied to the options container
• role="option" — applied to each selectable item
• aria-expanded — indicates whether the dropdown is open
• aria-controls — links the trigger to the listbox
• aria-selected — indicates selected state of each option
• aria-autocomplete="list" — signals filter behaviour on the search input
• aria-activedescendant — tracks the currently focused option for screen readers
• Tag remove buttons must receive a descriptive aria-label (e.g., aria-label="Remove The Great Gatsby") — the consumer is responsible for providing this.

Catalyst adds the visual styling; Radix Popover provides the underlying focus-management and dismissal semantics. See the Radix Popover accessibility docs for inherited baseline behaviour.

Choosing the Right Component

Use ComboboxMulti when users need to search and select multiple items from a list. Reach for a different primitive when:

Related

• Combobox
• Select
• Tag
• Checkbox
• Popover