Combobox
NewPro
An autocomplete field that filters as you type, highlights the matches and follows the ARIA combobox pattern, with a loading state for results from a server.
Customize
Results from a server
Disabled
#ff784f
When to use it
- Choosing a country, city or server region from a long list
- Search-as-you-type against an API, such as finding a player or a product
- Assigning a person or a project in an admin form
Good to know
- Plan
- Pro
- Dependencies
- motion
- Rendering
- DOM and CSS
- Reduced motion
- Respected
- Lines of code
- 491
Installation
Combobox is part of Pro. After purchase you're invited to the private mekai-ui/mekai-ui-pro GitHub repository: copy combobox.tsx into components/ui and run npm install motion.
Usage
import { Combobox } from "@/components/ui/combobox";
<Combobox
label="Player"
name="playerId"
options={results}
loading={searching}
filter={false}
onInputChange={search}
onChange={(id) => setPlayer(id)}
/>Props
20 properties| Property | Type | Default | Description |
|---|---|---|---|
| options | (ComboboxOption | string)[] | — | The list. An option has value, label, and optionally description, icon and disabled. |
| value | string | null | — | Controlled selection. Leave it out to let the field manage itself. |
| defaultValue | string | null | null | Starting selection when uncontrolled. |
| onChange | (value, option) => void | — | Called when the selection changes, with null when it is cleared. |
| onInputChange | (text: string) => void | — | Called with the text on every keystroke. Use it to fetch results. |
| filter | false | (option, query) => boolean | — | Your own match test, or false when the server already filtered the options. By default every typed word must appear in the label or description, ignoring case and accents. |
| loading | boolean | false | Shows a spinner, and placeholder rows until results arrive. Earlier results stay visible, dimmed. |
| label | string | — | Visible label above the field. |
| placeholder | string | "Search" | Native placeholder. |
| hint | string | — | Helper text under the field while there is no error. |
| error | boolean | string | — | Marks the field invalid. A string is shown as the message. |
| emptyMessage | string | "No matches" | Shown when nothing matches. |
| color | string | "#ff784f" | Accent for focus and highlighted matches. |
| disabled | boolean | false | Blocks interaction and leaves the field out of form data. |
| required | boolean | — | Native required attribute. |
| name | string | — | Form field name. Submits the selected value, not the typed text. |
| id | string | — | Base id for the input and the list. |
| defaultOpen | boolean | false | Starts with the list open. |
| defaultQuery | string | — | Starting search text. |
| className | string | — | Extra classes for the wrapper. |
Dependencies: motion