Combobox
A text field that suggests matching options as you type. Label, optional helper text, and an error state.
Usage
Import the component and render it.
import { Combobox } from 'src/components/Combobox/Combobox';
import { LifebuoyIcon } from '@phosphor-icons/react';
<Combobox
size="sm"
label="Label"
placeholder="Select option"
helperText="Helper text"
icon={<LifebuoyIcon />}
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
/>Accessibility
Role: editable combobox with list autocomplete: an <input role="combobox" aria-autocomplete="list"> controlling a role="listbox" of options.
| Key | Action |
|---|---|
| Typing | Filters the options and opens the list (nothing is highlighted until the arrows are used) |
| ↓ / ↑ | Opens the list, or highlights the next / previous match (disabled ones are skipped; focus stays in the input) |
| Enter | Chooses the highlighted match: its label fills the input and the list closes |
| Escape | Closes the list; a second Escape clears the text |
| Tab | Closes the list and moves on |
- Clicking the input or the Caret Icon opens the list; the caret is a "Show options" button that also closes it, and keeps focus in the input.
- The label names the input and the helper text describes it; with error, aria-invalid is set and the helper text is the error message.
- When nothing matches, the empty message is a live status (announced), not an option.
- A click outside closes the list.
Size
Set the size prop: Small is "sm", Medium is "md".
<Combobox
size="sm"
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
/>
<Combobox
size="md"
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
/>States
Disabled comes from the disabled prop; Error from the error prop; Filled from the content (value); No-Items from the content (defaultInputValue). Hover and Focus follow the pointer and the keyboard: try them in the playground.
No items found
<Combobox
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
disabled
/>
<Combobox
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
error
/>
<Combobox
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
value="one"
/>
<Combobox
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
defaultInputValue="Option five"
/>Composition
Use the following composition to build a Combobox:
Combobox
└── ComboboxItemComboboxItem
One suggestion of a Combobox: an optional icon, a label, an optional description, and a check on the chosen one. Only used inside Combobox.
Option labelDescription text
<ComboboxItem label="Option label" />Actions
Pass callbacks to respond to the component.
import { Combobox } from 'src/components/Combobox/Combobox';
import { LifebuoyIcon } from '@phosphor-icons/react';
<Combobox
size="sm"
label="Label"
placeholder="Select option"
helperText="Helper text"
icon={<LifebuoyIcon />}
options={[{"value":"one","label":"Option label","description":"Description text","icon":<LifebuoyIcon />},{"value":"two","label":"Option two","description":"Description text","icon":<LifebuoyIcon />},{"value":"three","label":"Option three","description":"Description text","icon":<LifebuoyIcon />},{"value":"four","label":"Option four","description":"Description text","icon":<LifebuoyIcon />}]}
onValueChange={(value) => console.log(value)}
onOpenChange={(open) => console.log(open)}
/>| Callback | When |
|---|---|
onValueChange | Called with the chosen option value. |
onOpenChange | Called when the list opens or closes. |