CatalystComboboxv0.3.3Documentation Under Review
A searchable dropdown component that combines an input field with a list of filterable options. Built with Radix UI primitives for robust accessibility.
Prefer AI-assisted development?
Catalyst Combobox combines a text input with a Radix UI Popover to deliver a fully accessible searchable dropdown — with built-in keyboard navigation, ARIA semantics, and design-token styling out of the box.
Installation
npm install '@pmi/catalyst-combobox'import {
ComboboxTrigger,
ComboboxInput,
ComboboxItem,
ComboboxPopover,
ComboboxSeparator,
ComboboxScrollButton,
} from '@pmi/catalyst-combobox';Variants
Default
A standard combobox with search filtering and option selection.
Danger
Use the danger variant to indicate errors or destructive actions:
Sizes
The Combobox component supports three size variants: sm (small), md (medium), and lg (large):
Common Patterns
With Badges
Display badges alongside options to provide additional context or categorization.
Double with Avatar
A production-ready example combining avatars and status indicators.
API Reference
Combobox is a compound component built on Radix UI primitives. The sections below summarize the shared API surface for each part of the component.
ComboboxTrigger
The button that opens the dropdown. Supports ref forwarding.
Prop
Type
Extends
HTMLAttributes<HTMLDivElement>.
ComboboxInput
The search input field with icon support.
Prop
Type
Extends
HTMLAttributes<HTMLDivElement>.
ComboboxItem
An individual selectable option.
Prop
Type
Extends
HTMLAttributes<HTMLDivElement>.
ComboboxSeparator
A visual divider between sections.
Prop
Type
ComboboxScrollButton
Scroll control buttons (up/down) for long option lists.
Prop
Type
ComboboxPopover
Container for the dropdown content. Accepts all standard Radix Popover Content props.
Prop
Type
Accessibility
Combobox is designed to meet WCAG 2.2 AA standards.
Keyboard Interactions
| Key | Action |
|---|---|
Enter or Space | Opens/closes the dropdown when trigger is focused |
Escape | Closes the dropdown and returns focus to trigger |
↓ / ↑ | Navigates through options |
Tab | Moves focus to the next focusable element |
ARIA
This combobox uses direct focus management rather than aria-activedescendant. Each option receives actual DOM focus when navigated with arrow keys, providing clearer visual feedback via :focus-visible styles and consistent cross-browser scrolling behaviour.
role="combobox"— applied to the input fieldrole="listbox"— applied to the options containerrole="option"— applied to each selectable itemaria-expanded— indicates whether the dropdown is openaria-controls— links the trigger to the listboxaria-selected— indicates the currently selected optionaria-autocomplete="list"— signals filter behaviourtabIndex={-1}— options receive programmatic focus via arrow keys (roving tabindex pattern)
Catalyst adds the visual styling and token colours; Radix provides the underlying accessibility semantics. See the Radix Popover accessibility docs for inherited baseline behaviour.
Choosing the Right Component
Use Combobox when users need to search or filter a list before selecting an option. Reach for a different primitive when:
| If you need… | Use instead |
|---|---|
| A simple dropdown without search | Select |
| Free-text input with suggestions (not strict options) | Autocomplete |
| A floating panel without selection semantics | Popover |
Related
ComboboxMulti
A multi-select combobox component with search, tags, and keyboard navigation for selecting multiple items from a list.
File Upload
A flexible file upload component with drag-and-drop support, file validation, progress tracking, and customizable trigger coloration built for product applications.