组件

Combobox

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.

安装

terminal
npx shadcn@latest add @wobko/combobox

第一次使用?先把 registry 加进 components.json。 如何安装

示例

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.

Labels as hang-tags

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.

Create what you typed

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.

Results from a server

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".

An editable field in a form

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.

A filter inside a menu

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.

Popover and Command, by hand

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.

Responsive: popover or drawer

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.

API 参考

Combobox

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).

属性类型默认值说明
value / defaultValue / onValueChangestring | null | string[] (multiple)-One value, or an array with `multiple`. `value={null}` is a controlled, empty single-select.
multiplebooleanfalseChoose 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 / onInputValueChangestring-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.
loadingbooleanfalseResults are on their way: `ComboboxEmpty` waits so a search in flight is not answered with 'no results'.
namestring-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 / invalidboolean-As on an input; invalid draws the red pencil box.
readOnlybooleanfalseThe 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.
requiredbooleanfalseA 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.)
labelstring-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.
announcefalse | ({ 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.

ComboboxTrigger

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).

属性类型默认值说明
seedstring | number-Pins the hand: the same seed always draws the same box.

ComboboxValue

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`).

属性类型默认值说明
placeholderReactNode-Shown while nothing is chosen.

ComboboxContent

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.

属性类型默认值说明
anchorRefObject<Element>-Line the list up with another element (from `useComboboxAnchor`).

ComboboxInput

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.

属性类型默认值说明
showTriggerbooleantrueField mode: the chevron button that toggles the list.
showClearbooleanfalseField mode: a small x that empties the field once something is chosen.

ComboboxCollection

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).

属性类型默认值说明
items(string | { value, label?, disabled?, keywords? })[]-Default: the root's items.

ComboboxItem

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.

属性类型默认值说明
valuestring-What is stored.
labelstring-The text of the row for filtering and for the trigger, when the children are not a plain string.
keywordsstring[]-More words that find the row.

ComboboxEmpty

What shows when nothing matches: Stubby with his magnifier and your words. Hidden while `loading`.

属性类型默认值说明
mascotbooleantrue`false` leaves Stubby out.

ComboboxCreate

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.

属性类型默认值说明
onCreate(text: string) => void-Called before the new value is chosen.
childrenReactNode | ((text: string) => ReactNode)`Create "text"`The row's text.

ComboboxChips

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.

属性类型默认值说明
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.

ComboboxChip

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.

属性类型默认值说明
valuestring-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.
showRemovebooleantrueLeave the x out.

无障碍

  • The trigger is a `role=combobox` button with `aria-haspopup="dialog"` (Radix's: the popup is a dialog holding the search box and the list), `aria-expanded` and, when `required`, `aria-required`; it needs a name (`aria-label` or a Label with `htmlFor`). The list opens in a named dialog (the root's `label`) holding cmdk's search combobox and listbox; focus goes to the search box and Escape closes and returns focus to the trigger.
  • In field mode (`ComboboxInput` on its own, `ComboboxChips`) the input is the combobox: focus never leaves it, ArrowDown / ArrowUp open the list, the arrow keys move the highlight, Enter chooses, Escape closes. `aria-expanded` follows the list.
  • Chosen rows say "selected" to screen readers as well as showing a tick. Tags are named "Remove <label>" on their x; Backspace in the empty input removes the last one. In a `multiple` combobox a polite status says what was added or removed (a tag taken back leaves nothing else to hear).
  • The input's `aria-activedescendant` always names the row that is highlighted, after every keystroke and every arrow key, and is dropped when the list is closed or empty (cmdk records it before it has redrawn the rows, so after typing it named a row that was gone; the same fix is in `CommandInput`).
  • Pressing a row with the mouse does not pull the focus out of the search box, so you can pick a tag and keep typing (or press Backspace); the x on a tag hands the focus back to the input.
  • A polite status under the search box says how many results are left; the empty message and the loading row are announced by cmdk's own roles (`progressbar` for Loading).
  • Nothing depends on hue alone: the highlighted row is a highlighter shape, the chosen row has a tick and a text cue, tags are shapes with a label and a remove button. In Windows high contrast the field gets a real border.
  • Touch: the trigger is 36 px tall (32 compact, 28 calm), rows 36 px, the tag's x is a 24 px target.

源码

CLI 会复制进你项目的文件。

正在加载源码