import { Combobox } from "capsomer/react/combobox";
<Combobox
label="Site"
items={[{ value: "docs", label: "Docs" }, { value: "shop", label: "shop.example.com" }]}
value={site}
onValueChange={setSite}
placeholder="For example: docs"
help="Only a listed site can be chosen."
/>
import { ComboboxMultiple } from "capsomer/react/combobox";
<ComboboxMultiple label="Sites to back up" items={sites} values={ids} onValuesChange={setIds} />
Options from a server as the person types, in place of filtering items here: search gets the typed text and an AbortSignal (a newer keystroke aborts the older request) and returns the matches. items then holds only options known before any search (the chosen one, so its label shows). Waits searchDelay ms (200) after the last key, and asks nothing for fewer than minSearchLength characters (1).
searchDelay
number
minSearchLength
number
searchHint
string
What the list says before a search can run, and when one fails.
searchFailedText
string
ComboboxFreeText
Prop
Type
Required
Does
items
ComboboxOption[]
Suggestions to filter here. With search they are not needed.
value
string
The typed text is the value: any text can be kept, and a suggestion only fills it in.
defaultValue
string
onValueChange
(text: string) => void
onPick
(item: ComboboxOption) => void
A suggestion was picked, for filling the fields that come with it (an institution’s city). It runs after onValueChange, so what it sets stands.
disabled
boolean
name
string
The form field name of the hidden input that carries the value.
id
string
label
string
Yes
The visible label above the box. Required: a combobox always has one.
placeholder
string
An example only, never the label (patterns.md, "Form").
loading
boolean
The items are still arriving: the popup says so instead of "no match".
loadingText
string
help
ReactNode
Help under the label, outside the box; also where a disabled box says why.
error
ReactNode
The error, beside the field: marks the box invalid and describes it.
required
boolean
container
HTMLElement | null
Where the popup is portaled. Inside a modal <dialog> pass the dialog, or the popup renders under the top layer, out of sight.
defaultOpen
boolean
For specimens and tests: open on mount, with this text typed.
Options from a server as the person types, in place of filtering items here: search gets the typed text and an AbortSignal (a newer keystroke aborts the older request) and returns the matches. items then holds only options known before any search (the chosen one, so its label shows). Waits searchDelay ms (200) after the last key, and asks nothing for fewer than minSearchLength characters (1).
searchDelay
number
minSearchLength
number
searchFailedText
string
ComboboxMultiple
Prop
Type
Required
Does
values
string[]
The chosen values, controlled. Leave undefined to let the combobox hold them.
defaultValues
string[]
onValuesChange
(values: string[]) => void
creatable
boolean
A tag field: typed text that is not in items can be added as a value of its own. A first row, Create “text”, offers it; Enter takes it (text that matches an item, ignoring case, picks that item instead, so a tag is never made twice). The value of a made one is its text.
createLabel
(text: string) => string
The words of the create row, from the typed text.
label
string
Yes
The visible label above the box. Required: a combobox always has one.
items
ComboboxOption[]
Yes
placeholder
string
An example only, never the label (patterns.md, "Form").
emptyText
ReactNode | ((query: string) => ReactNode)
What an empty result says. A function gets the typed text, to name the filter.
loading
boolean
The items are still arriving: the popup says so instead of "no match".
loadingText
string
help
ReactNode
Help under the label, outside the box; also where a disabled box says why.
error
ReactNode
The error, beside the field: marks the box invalid and describes it.
disabled
boolean
required
boolean
name
string
The form field name of the hidden input that carries the value.
id
string
container
HTMLElement | null
Where the popup is portaled. Inside a modal <dialog> pass the dialog, or the popup renders under the top layer, out of sight.
defaultOpen
boolean
For specimens and tests: open on mount, with this text typed.
Options from a server as the person types, in place of filtering items here: search gets the typed text and an AbortSignal (a newer keystroke aborts the older request) and returns the matches. items then holds only options known before any search (the chosen one, so its label shows). Waits searchDelay ms (200) after the last key, and asks nothing for fewer than minSearchLength characters (1).
searchDelay
number
minSearchLength
number
searchHint
string
What the list says before a search can run, and when one fails.
searchFailedText
string
CSS variables
Variable
Default
--anchor-width
set by the page
--available-height
set by the page
--available-width
set by the page
--listbox-max
min(22rem, var(--available-height))
Parts and data attributes
Class
Is
.cap-combobox
the root
.cap-combobox-chip
a part
.cap-combobox-chip-remove
a part
.cap-combobox-chips
a part
.cap-combobox-clear
a part
.cap-combobox-empty
a part
.cap-combobox-error
a part
.cap-combobox-group
a part
.cap-combobox-help
a part
.cap-combobox-input
a part
.cap-combobox-label
a part
.cap-combobox-list
a part
.cap-combobox-popup
a part
.cap-combobox-positioner
a part
.cap-combobox-status
a part
.cap-combobox-trigger
a part
Attribute
Values
data-disabled
present or absent
data-empty
present or absent
data-highlighted
present or absent
data-popup-open
present or absent
State
Read from
:disabled
the platform
:empty
the platform
:focus-visible
the platform
:hover
the platform
[aria-invalid="true"]
an attribute
Accessibility
Key
Does
ArrowDown
Opens the list; then moves the highlight down
ArrowUp
Moves the highlight up
Typing
Filters the list
Enter
Chooses the highlighted option and closes the list
Esc
Closes the list; the box keeps focus and shows the chosen value
Tab
Leaves the box; the list closes
The input is the combobox; it is named by its label and described by help and error.
The open button is out of the tab order (Base UI, tabindex="-1") and has a name for pointer and voice users. So does the clear button ("Clear Site"), and each chip's remove button ("Remove Docs"), at least --target square.
Forced colors: the highlighted option gets a Highlight outline, since its tint is removed.
Inside a modal dialog, pass the dialog as container, or the popup renders under the top layer, out of sight.