Design Systemv0.21.0

primitives/@mihcm/ui·v0.21.0·stable

Combobox

Autocomplete search input combining a text field with a filterable dropdown list. Ideal for large option sets.

Configurator Examples Usage Accessibility Api

Combobox -- Accessibility

Keyboard

Key	Action
`Enter` / `Space`	Opens the dropdown when the trigger is focused.
`ArrowDown`	Moves highlight to the next option. Opens the dropdown if closed.
`ArrowUp`	Moves highlight to the previous option.
`Enter`	Selects the currently highlighted option and closes the dropdown.
`Escape`	Closes the dropdown without changing the selection.
`Home`	Moves highlight to the first option.
`End`	Moves highlight to the last option.
Printable characters	Filters the options list by typing into the search input.

When the dropdown is closed, focus remains on the trigger so the user can tab to the next form control normally.

ARIA roles

Element	Attribute	Value
Trigger	`role`	`combobox`
Trigger	`aria-expanded`	`true` when dropdown is open, `false` otherwise
Trigger	`aria-haspopup`	`listbox`
Trigger	`aria-controls`	ID of the listbox element
Trigger	`aria-activedescendant`	ID of the currently highlighted option
Dropdown	`role`	`listbox`
Option	`role`	`option`
Option	`aria-selected`	`true` on the selected option
Search input	`aria-autocomplete`	`list`

When the dropdown opens, screen readers announce the number of available options.
As the user types, the filtered count is announced via a live region (e.g. "3 results available").
When an option is highlighted with arrow keys, its label is announced.
On selection, the selected value is announced and the dropdown closes.
When no options match the search, an "No results found" message is announced.

Reduced motion

When prefers-reduced-motion: reduce is active:

The dropdown open/close animation is replaced with a simple show/hide.
Scroll-into-view for the highlighted option uses instant scrolling instead of smooth scrolling.

Native (React Native)

Uses Modal with FlatList for the dropdown.
TextInput for search filtering.
accessibilityRole="combobox" on the trigger.
Options use accessibilityRole="menuitem" with accessibilityState={{ selected }}.
Android back button closes the dropdown via onRequestClose.

Best practices

Always provide a meaningful placeholder.
Show an empty state message when no options match the search.
For very large lists (1000+), consider virtualised rendering.
Pair the combobox with a visible <label> in form contexts for proper screen reader association.
Avoid dynamically changing the options list while the dropdown is open, as this can disorient assistive technology users.