Combobox
A searchable single- or multi-select with ranked options
Assigned: ada · Shown as: Ada Lovelace
Labels
Disabled
Values: perf, docs
Installation
npx shadcn@latest add @sudokw/components-comboboximport { Combobox } from "@gpuixui/components";Usage
import { useState } from "react";
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxList,
ComboboxTrigger,
} from "@gpuixui/components/combobox";
const people = [
{
value: "ada",
label: "Ada Lovelace",
description: "Engineering · compilers",
},
{
value: "grace",
label: "Grace Hopper",
description: "Platform · releases",
},
];
export const ReviewerField = () => {
const [reviewer, setReviewer] = useState<string | null>("ada");
return (
<Combobox
onValueChange={(value) =>
setReviewer(typeof value === "string" ? value : null)
}
options={people}
value={reviewer ?? undefined}
>
<ComboboxTrigger label="Reviewer" placeholder="Choose a reviewer…" />
<ComboboxContent>
<ComboboxInput label="Search reviewers" />
<ComboboxList label="Reviewers" />
<ComboboxEmpty />
</ComboboxContent>
</Combobox>
);
};Composition
Combobox
├── ComboboxTrigger
└── ComboboxContent
├── ComboboxInput
├── ComboboxList
│ └── ComboboxItem
└── ComboboxEmptyAPI reference
Combobox
| Prop | Type | Default |
|---|---|---|
options | ReadonlyArray<ComboboxOption> — { value, label, description?, disabled? } | required; a stored value that is not a list paints no rows |
value | string | ReadonlyArray<string> — controlled | uncontrolled; a stored value that is neither text nor a list means uncontrolled |
defaultValue | string | ReadonlyArray<string> — initial selection when uncontrolled | — |
onValueChange | (value: string | null | ReadonlyArray<string>) => void | — |
multiple | boolean | false |
disabled | boolean | false |
onQueryChange | (query: string) => void — every search the popup runs, including the empty one it opens with | — |
shouldFilter | boolean — rank options locally; false keeps the caller's order | true |
loading | boolean — the caller's fetch is in flight; an empty list says Searching… | false |
onCreate | (query: string) => void — single mode only; the caller adds the option | — |
createLabel | (query: string) => string | Create "…" |
children | parts — ComboboxTrigger, ComboboxContent | — |
ComboboxTrigger
| Prop | Type | Default |
|---|---|---|
placeholder | string — shown while nothing is selected | "Select…" |
label | string — the trigger's accessible name | — |
className | string — joined after the trigger recipe | — |
testId | string | "combobox-trigger" |
ComboboxContent
| Prop | Type | Default |
|---|---|---|
side | "top" | "right" | "bottom" | "left" | "bottom" — a stored name the union does not carry |
align | "start" | "center" | "end" | "start" — a stored name the union does not carry |
sideOffset | number — the gap to the trigger | 4 |
alignOffset | number — added on top of the measured centre correction | 0 |
className | string — joined after the surface recipe | — |
children | parts — ComboboxInput, ComboboxList, ComboboxEmpty | — |
ComboboxInput
| Prop | Type | Default |
|---|---|---|
placeholder | string | "Search…" |
label | string | "Search options" |
ComboboxList
| Prop | Type | Default |
|---|---|---|
label | string — the listbox's accessible name | "Options" |
itemStyle | StateStyle<ComboboxItemState> — resolved per row | the recipe |
ComboboxItem
| Prop | Type | Default |
|---|---|---|
value | string — the label and description are read from the root's option | required |
style | StateStyle<ComboboxItemState> — { selected, highlighted, disabled } | the recipe |
ComboboxEmpty
| Prop | Type | Default |
|---|---|---|
children | ReactNode | No matches |
Keyboard
- Arrow DownArrow Up
- opens the list from the trigger, and moves the highlight from the field
- Ctrl+NCtrl+P
- moves the field's highlight by the same step
- Escape
- closes the open list
Enter runs the highlighted option through the field's own submit.
read from combobox.tsx, combobox.js in the pinned GPUix runtime
Edit this page on GitHubapps/docs/content/docs/components/combobox.mdx