Combobox
DraftA searchable dropdown select supporting single and multi-select, creatable options, and keyboard navigation.
- Usage
- Specs
- Content
- Status & changelog
- Code
Common alternative names
Autocomplete, typeahead, searchable select
Usage guidelines coming soon.
Specs coming soon.
Content guidelines coming soon.
Status & changelog coming soon.
Usage
import { Combobox } from '@arch-ui/components';
function Example() {
const [selected, setSelected] = React.useState('');
const [search, setSearch] = React.useState('');
return (
<Combobox
options={[
{ id: 'us', label: 'United States' },
{ id: 'ca', label: 'Canada' },
{ id: 'gb', label: 'United Kingdom' },
]}
value={selected}
onChange={setSelected}
inputValue={search}
onInputChange={setSearch}
/>
);
}
Multi-select
In multi-select mode, selected options appear as removable tags inside the control.
<Combobox
multi
options={options}
value={selectedIds}
onChange={setSelectedIds}
inputValue={search}
onInputChange={setSearch}
placeholder="Select countries..."
/>
Creatable
Allow users to create new options that don't exist in the list.
<Combobox
creatable
options={options}
value={selected}
onChange={setSelected}
onCreate={(newLabel) => addOption(newLabel)}
inputValue={search}
onInputChange={setSearch}
/>
Sizes
| Size | Min height | Font scale |
|---|---|---|
mini | 28px | Paragraph XSmall |
compact | 36px | Paragraph Small |
default | 48px | Paragraph Medium |
large | 56px | Paragraph Large |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
options | { id: string; label: string; disabled?: boolean }[] | required | The list of selectable options. |
value | string | string[] | undefined | The currently selected option id(s). |
onChange | (value: string | string[]) => void | undefined | Called when the selection changes. |
inputValue | string | '' | Controlled search text value. |
onInputChange | (value: string) => void | undefined | Called when the search input text changes. |
multi | boolean | false | Enables multi-select mode with tag display. |
creatable | boolean | false | Allows creating new options from the search text. |
onCreate | (value: string) => void | undefined | Called when a new option is created. |
clearable | boolean | true | Shows a clear button when a selection exists. |
searchable | boolean | true | Allows typing to filter options. |
disabled | boolean | false | Disables the combobox. |
placeholder | string | 'Select...' | Placeholder text when no value is selected. |
size | 'mini' | 'compact' | 'default' | 'large' | 'default' | Size variant. |
positive | boolean | false | Shows a positive (success) border style. |
error | boolean | false | Shows an error border style. |
className | string | undefined | Additional CSS class names. |
Accessibility
- The input uses
role="combobox"witharia-expanded,aria-autocomplete="list", andaria-controlspointing to the listbox. - The dropdown uses
role="listbox"withrole="option"for each item. aria-activedescendanttracks the currently focused option for screen readers.- In multi-select mode, the listbox uses
aria-multiselectable. - Arrow keys navigate options, Enter selects, Escape closes the dropdown.
- Backspace in multi-select mode removes the last selected tag when the input is empty.
- Disabled options are marked with
aria-disabledand skipped during keyboard navigation. - The clear button uses
aria-label="Clear selection". - The dropdown is rendered via Portal to avoid clipping.
- The component is
forwardRefcompatible.
Best practices
Do:
- Use Combobox when the option list is long enough to benefit from search filtering.
- Use
multifor tag-style multi-selection (e.g., categories, skills). - Use
creatablewhen users should be able to add new values not in the predefined list. - Provide controlled
inputValueandonInputChangefor server-side filtering.
Don't:
- Do not use Combobox for short lists of 3-5 options -- use Select or Radio instead.
- Do not use Combobox when the options are static and short -- native Select is simpler and more accessible.
Design tokens
| Token | Role |
|---|---|
color-background-default | Control background |
color-border-default | Default border |
color-border-focus | Focus border and outline |
color-border-danger | Error state border |
color-border-success | Positive state border |
color-background-disabled | Disabled control background |
color-surface-base | Dropdown background |
color-background-muted | Focused option highlight |
shadow-shallow-above | Dropdown shadow |
z-semantic-dropdown | Dropdown z-index |
radius-component-md | Control and dropdown corner radius |