Framework picker
The shadcn recipe: press the field, type to narrow ("svelte" finds SvelteKit), arrow keys and Enter to choose. The chosen row ends in a blue tick. Try a word that matches nothing to meet Stubby.
A field you can search. Press it and a command list opens on a slip; type to narrow it, arrow keys and Enter to choose. It can be the single-select of the shadcn docs, an editable field, or a multi-select whose choices are hand-drawn hang-tags you can take back; it can offer to create what you typed and wait for results from a server.
npx shadcn@latest add @wobko/comboboxFirst time here? Add the registry to components.json first. How to install
The shadcn recipe: press the field, type to narrow ("svelte" finds SvelteKit), arrow keys and Enter to choose. The chosen row ends in a blue tick. Try a word that matches nothing to meet Stubby.
A multi-select whose choices are tags on a string: each a little different, a punched hole at the point, the x wearing the highlighter when you reach for it. Click anywhere in the field to type; Backspace in the empty input takes the last tag back. tone="auto" gives each label its own color.
Type a name that is not in the list and the last row offers to add it. Choosing it calls onCreate (you add it to your list) and then chooses it. An exact match, in any case, hides the offer.
Filtering is off (shouldFilter={false}) and the search text is watched: while a request is in flight the loops show and the empty message waits. Try "gra" (two people), then "zzz".
ComboboxInput on its own is the field: it shows the chosen country until you type, opens as you type, and puts the country back if you close without choosing. The hidden input (name) submits the code.
The shadcn recipe for "apply a label": a row's action menu has a sub-menu, and the sub-menu holds a Command, so a long list of labels can be searched with the keyboard. The palette puts its own slip away inside a menu, because the menu is already the paper.
The composable recipe behind the Combobox: a button with `role="combobox"`, a Popover that opens to its side, and a Command inside it for the search and the rows. Reach for it when you want full control of the trigger; the Combobox component wraps the same parts and adds the form value.
One list, two shells: a popover next to the button on a wide screen, a drawer from the bottom on a phone, where a small floating box is hard to hit. The media query is read with useSyncExternalStore, so the server renders the popover and a phone swaps after hydration.
The root. Holds the value, the open state and the search text, and wraps its children in a cmdk `Command` with no box of its own, so the search input can live in the list or in the field. **Deviation from upstream:** shadcn's new Combobox is built on base-ui; this one is Popover + Command (cmdk) + a field, the recipe shadcn documented before base-ui. The part names are the same where they make sense. Values are strings (the item's `value`), not objects; the label of an item is its text (or `label`, or the `items` you give the root); the search field is a child of `ComboboxContent`, not of the trigger; `ComboboxCollection` takes plain `items` (no `Group items`); `ComboboxChips` draws one tag per chosen value itself, so upstream's `<ComboboxValue>{(values) => values.map(...)}</ComboboxValue>` becomes `renderChip` (or nothing).
| Prop | Type | Default | Description |
|---|---|---|---|
| value / defaultValue / onValueChange | string | null | string[] (multiple) | - | One value, or an array with `multiple`. `value={null}` is a controlled, empty single-select. |
| multiple | boolean | false | Choose several. Choosing toggles and keeps the list open. |
| items | (string | { value, label?, disabled?, keywords? })[] | - | Optional. Gives every value its label while the list is closed (a trigger or tag can show it before any row was mounted) and feeds a render-function `ComboboxList`. |
| open / defaultOpen / onOpenChange | - | Control the list. | |
| inputValue / defaultInputValue / onInputValueChange | string | - | The search text. Cleared when the list closes. |
| shouldFilter / filter / loop | - | cmdk's: `shouldFilter={false}` to filter yourself (a server search), `filter` for your own scoring, `loop` to wrap the arrow keys. | |
| loading | boolean | false | Results are on their way: `ComboboxEmpty` waits so a search in flight is not answered with 'no results'. |
| name | string | - | Hidden inputs, one per chosen value, for forms (one empty one when nothing is chosen). A form reset puts an uncontrolled combobox back to its `defaultValue`, like a native input (a controlled one is yours to reset). |
| disabled / invalid | boolean | - | As on an input; invalid draws the red pencil box. |
| readOnly | boolean | false | The value is shown (and submitted) but the list will not open and nothing can be chosen, removed or cleared. `aria-readonly` on the trigger, `readonly` on the input, disabled remove buttons on the tags. |
| required | boolean | false | A form will not submit while nothing is chosen. (A hidden input is exempt from form validation, so an invisible empty field does the failing; it sends the focus to the combobox. `aria-required` is set on the trigger or the input.) |
| label | string | - | Accessible name of the list and of the dialog it sits in. Give it: without it a chips field or an editable input has no name. |
| announce | false | ({ added, removed }) => string | - | `multiple` only: what the polite status says when values are added or removed ("Astro selected", "Astro removed"). Translate it, or `false` for none. |
The field you press: a `<button role="combobox">` in the select trigger's pencil box with `chevrons-up-down` at its end. ArrowDown / ArrowUp / Enter / Space open the list. Put a ComboboxValue in it (that is the default child).
| Prop | Type | Default | Description |
|---|---|---|---|
| seed | string | number | - | Pins the hand: the same seed always draws the same box. |
What is chosen, as text: the label(s), comma separated, in blue felt, or the `placeholder` in graphite. A function child gets `(value, labelFor)` to draw it yourself (`n selected`).
| Prop | Type | Default | Description |
|---|---|---|---|
| placeholder | ReactNode | - | Shown while nothing is chosen. |
The slip the list sits on: a Popover as wide as the field (the paper carries `data-slot="popover-content"`, with `data-slot="combobox-content"` on the box inside). It takes the PopoverContent props (`side`, `align`, `sideOffset`, `pin`, `tape`, `stock`...). When the field is its own search box the focus stays in the field.
| Prop | Type | Default | Description |
|---|---|---|---|
| anchor | RefObject<Element> | - | Line the list up with another element (from `useComboboxAnchor`). |
Two things, by where it is. Inside `ComboboxContent`: the search box of the list (magnifier, blue felt text, a rule drawn under it). On its own, under `Combobox`: the field itself, an editable single-select that shows the chosen label until you type, opens as you type and puts the label back if you close without choosing.
| Prop | Type | Default | Description |
|---|---|---|---|
| showTrigger | boolean | true | Field mode: the chevron button that toggles the list. |
| showClear | boolean | false | Field mode: a small x that empties the field once something is chosen. |
As upstream: one child per item, from its own `items` or the root's (`{(item) => <ComboboxItem value={item.value}>{item.label}</ComboboxItem>}`). It renders no element (cmdk sorts rows inside their group, and a wrapper would be in the way).
| Prop | Type | Default | Description |
|---|---|---|---|
| items | (string | { value, label?, disabled?, keywords? })[] | - | Default: the root's items. |
One choice. `value` is what the combobox stores; the label is the text inside (or `label`); both are searched (plus `keywords`). The chosen row ends in a blue tick and says 'selected' to screen readers. Choosing in a single combobox closes the list.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | - | What is stored. |
| label | string | - | The text of the row for filtering and for the trigger, when the children are not a plain string. |
| keywords | string[] | - | More words that find the row. |
What shows when nothing matches: Stubby with his magnifier and your words. Hidden while `loading`.
| Prop | Type | Default | Description |
|---|---|---|---|
| mascot | boolean | true | `false` leaves Stubby out. |
The last row when what is typed is not one of the items: 'Create "text"'. Choosing it calls `onCreate(text)` (add it to your list there) and then chooses the text.
| Prop | Type | Default | Description |
|---|---|---|---|
| onCreate | (text: string) => void | - | Called before the new value is chosen. |
| children | ReactNode | ((text: string) => ReactNode) | `Create "text"` | The row's text. |
The field of a `multiple` combobox: a pencil box that holds one removable tag per chosen value and the input. Click anywhere in it to type; Backspace in the empty input takes the last tag back. It is the anchor of the list.
| Prop | Type | Default | Description |
|---|---|---|---|
| tone | "hi" | "sky" | "grass" | "bubblegum" | "auto" | "hi" | Color of the tags; `auto` gives each value its own, from its text. |
| renderChip | (value, label) => ReactNode | - | Draw the tags yourself. |
One removable tag: a hang-tag drawn with its pointed end, a punched hole and a solid highlighter (or stationery-color) body, each a little different. The x is a real button named 'Remove <label>' that wears the highlighter on hover.
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | - | The value the x removes. Optional, as upstream: a text child is the value when this is not given. |
| tone | "hi" | "sky" | "grass" | "bubblegum" | "hi" | Color of the body. |
| showRemove | boolean | true | Leave the x out. |
The files the CLI copies into your project.
Loading the source