ComboboxMulti

v0.3.3

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,
  ComboboxMultiInput,
  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.

Common Patterns

With Badges

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

Custom Styling

Override the default Catalyst tokens with custom Tailwind classes and a custom checkbox CVA to match a brand palette.

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>.

ComboboxMultiInput

The search input field with icon support rendered inside the popover.

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