Combobox
Search and choose from known options.
Installation
pnpm dlx shadcn@4.18.0 add @siteplane/comboboxComplete the one-time setup first. Registry JSON lists source files and dependencies.
For this page’s examples, also install:
pnpm dlx shadcn@4.18.0 add @siteplane/button @siteplane/form @siteplane/input @siteplane/selectField is installed with Input.
Usage
import {
Combobox,
ComboboxInput,
ComboboxPopup,
ComboboxEmpty,
ComboboxList,
ComboboxItem,
} from "@/siteplane/components/combobox";
<Combobox items={["Design"]}>
<ComboboxInput aria-label="Workspace" />
<ComboboxPopup>
<ComboboxEmpty>No matching workspaces.</ComboboxEmpty>
<ComboboxList>
{(item: string) => (
<ComboboxItem key={item} value={item}>
{item}
</ComboboxItem>
)}
</ComboboxList>
</ComboboxPopup>
</Combobox>;An item shows its check in the leading slot. For identity rows that lead with an avatar or a logo, such as the people of an assignee picker, set indicatorPosition="end" on ComboboxItem: the row starts with its first child and ends with the check, and its label keeps one line, as on Menu radio items.
Composition
Combobox
├── ComboboxInput
└── ComboboxPopup
├── ComboboxStatus (optional)
├── ComboboxEmpty
└── ComboboxList → ComboboxItemControlled value and clear
The clear button updates the controlled value. Type a non-matching query to see the empty result.
Multiple selection
Set multiple and render the selected values as ComboboxChips inside ComboboxChips; each chip includes its own remove button. Use removeProps to give each remove button a specific name. Render the chips through ComboboxValue, as below: a chip that is added fades in, a removed chip fades out where it was, and the chips and the input after it glide to their new place. Reduced motion changes them at once. The field is as tall as an Input of the ComboboxChipsInput's size, and its chips are 20 px at sm, 24 px at md and lg and 32 px at xl. A chip is never wider than the field: a long value ends with an ellipsis and keeps its remove button, and the full value is the label's title, as on a Tag. The check of a selected item draws in when the item is picked and out when it is not, the way the Checkbox check does, and appears instantly under reduced motion.
Grouped options
Pass groups as items and render them with ComboboxGroup and ComboboxCollection. itemToStringLabel turns each object item into the text shown in the input and used for filtering.
Searchable select
When a long list needs search but the field should look like a Select, render ComboboxTrigger with SelectButton and put an embedded ComboboxInput inside the popup.
Variants and disabled
variant belongs to the input. Disabled prevents input interaction.
Sizes
size belongs to the input. Omit it to inherit the provider's control size.
Form integration
Place the combobox in a Field with a name; required blocks submission until a value is chosen and FieldError explains why. For object items, itemToStringValue decides the submitted string.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
item | (item: Value) => string | label for { value, label } items | Convert an object item to input display and filtering text. |
item | (item: Value) => string | value for { value, label } items | Convert an object item to its native form submission value; does not set display text. |
Combobox | sm | md | lg | xl | number | provider / lg | Visual size, or numeric native input size. |
Combobox | default | elevated | inset | default | Input surface. |
Combobox | boolean | true | Show popup toggle. |
Combobox | boolean | false | Show clear action. |
Combobox | ReactNode | unset | Leading content. |
Combobox | Trigger.Props / Clear.Props | unset | Configure generated action buttons. |
Combobox | Positioner side / alignment | bottom / start | Preferred position. |
Combobox | offsets | 4 / unset | Gap and alignment correction. |
Combobox | Positioner anchor | trigger/input or chips for multiple | Custom anchor. |
Combobox | Portal.Props | unset | Portal options. |
Combobox | start | end | start | Where the check shows: in the leading slot, or at the end of an identity row that leads with an avatar or a logo. |
value / default | selected Value or Value[] | uncontrolled | Selection |
on | (value, eventDetails) => void | unset | Value callback. |
on | (open, eventDetails) => void | unset | Popup visibility callback. |
Combobox | ComboboxInputProfile: default | embedded | default | Standard or embedded input surface. |
Combobox | input | standalone | input | Input surface, or a surface-free chip list below a separate ComboboxInput. |
Combobox | ReactNode | unset | Leading chip-container content. |
Combobox | default | elevated | inset | default | Chip-container surface. |
Combobox | control size | number | provider / lg | Input dimensions; the chips field and its chips follow them. |
Combobox | ChipRemove.Props | unset | Generated remove control props. |
Combobox preserves Base UI’s Value/Multiple generics and provides its context for chips/input anchoring. ComboboxInputProps omits the foundation render prop; use the documented embedded profile or public composition parts instead. ComboboxInputProfile is exported. ComboboxChips, Chip, ChipsInput and ChipRemove wrap the matching foundation parts; Chip supplies its own removal action by default. ComboboxContext exports chipsRef/inputRef (null) and multiple (false) defaults for the composition. Item forwards pointer events through its touch-selection guards. inputValue/onInputValueChange control the query independently from selected value. useComboboxFilter is the foundation filtering hook.
ComboboxList renders the filtered collection; Item represents a suggestion; Empty displays no results; Status provides status feedback. ComboboxGroup, ComboboxGroupLabel, ComboboxSeparator and ComboboxRow structure options. ComboboxValue renders the current value; ComboboxCollection supplies foundation collection composition. ComboboxTrigger and ComboboxClear are independently exported actions; their default render uses kit Buttons, and ComboboxTrigger also accepts render={<SelectButton />} for a select-style trigger. Popup includes Portal and Positioner; ComboboxList adds the ScrollArea. ComboboxPrimitive exports the namespace. Remaining root item-to-string/filter, keyboard, validation, disabled, readOnly, form, events and refs follow Base UI Combobox. Styled className props are strings. No independent fetch or loading service is supplied.
ComboboxTrigger and ComboboxClear accept their corresponding foundation props and default to a ghost Button with field-action profile and icon-xs size. Supply an accessible name when composing either action separately. ComboboxGroup, ComboboxGroupLabel, ComboboxRow, ComboboxSeparator, ComboboxValue, and ComboboxCollection accept their matching foundation part props with kit styling; they add no owned state API.
ComboboxChipRemove accepts foundation ChipRemove props and defaults to a bare icon-2xs text Button with an X icon and the accessible label “Remove”. Override the label through removeProps on ComboboxChip for additional context. Do not add a second removal button: Chip already renders this part.
Usage notes
Arrow keys navigate suggestions, Enter accepts and Escape dismisses. Keep a visible label in a production form. For async data, the application owns fetching, stale-result handling and pending/error status; render those states through Status and the surrounding field. See Choosing selection controls.