Skip to content

Combobox

A labeled text box that filters a list, where only a listed value can be chosen.

<div data-mount="closed"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/combobox.css";

Usage

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} />
import { Combobox, ComboboxFreeText } from "capsomer/react/combobox";
<Combobox label="Reviewer" items={[]} search={(q, signal) => findPeople(q, signal)} value={id} onValueChange={setId} />
<ComboboxFreeText label="Institution" value={name} onValueChange={setName} search={findInstitutions} minSearchLength={2} onPick={(i) => setCity(i.hint ?? "")} />

Examples

Closed, with a value chosen

<div data-mount="chosen"></div>

With a clear button

<div data-mount="clearable"></div>

Several values, as chips

<div data-mount="chips"></div>

A tag field: suggestions, and anything typed becomes a tag

<div data-mount="tags"></div>
<div data-mount="search"></div>

Free text with suggestions

<div data-mount="free"></div>

Comfortable density

<div data-mount="comfortable"></div>

Disabled, with its reason

<div data-mount="disabled"></div>

Invalid, with its message

<div data-mount="invalid"></div>

Open

<main class="specimen-page"><div data-mount="open"></div></main>

Filtered by typed text

<main class="specimen-page"><div data-mount="filtered"></div></main>

No match

<main class="specimen-page"><div data-mount="no-match"></div></main>

An option highlighted

<main class="specimen-page"><div data-mount="highlighted"></div></main>

Several values, open

<main class="specimen-page"><div data-mount="open-chips"></div></main>

A tag field, typing a new tag

<main class="specimen-page"><div data-mount="open-tags"></div></main>

Open, with group labels

<main class="specimen-page"><div data-mount="grouped"></div></main>

Loading

<main class="specimen-page"><div data-mount="loading"></div></main>

API reference

Combobox

PropTypeRequiredDoes
valuestring | nullThe chosen value, controlled. Leave undefined to let the combobox hold it (defaultValue). null is "nothing chosen".
defaultValuestring | null
onValueChange(value: string | null) => void
clearablebooleanA button in the box that clears the chosen value. It shows only while there is one.
labelstringYesThe visible label above the box. Required: a combobox always has one.
itemsComboboxOption[]Yes
placeholderstringAn example only, never the label (patterns.md, "Form").
emptyTextReactNode | ((query: string) => ReactNode)What an empty result says. A function gets the typed text, to name the filter.
loadingbooleanThe items are still arriving: the popup says so instead of "no match".
loadingTextstring
helpReactNodeHelp under the label, outside the box; also where a disabled box says why.
errorReactNodeThe error, beside the field: marks the box invalid and describes it.
disabledboolean
requiredboolean
namestringThe form field name of the hidden input that carries the value.
idstring
containerHTMLElement | nullWhere the popup is portaled. Inside a modal <dialog> pass the dialog, or the popup renders under the top layer, out of sight.
defaultOpenbooleanFor specimens and tests: open on mount, with this text typed.
defaultInputValuestring
search(query: string, signal: AbortSignal) => Promise<ComboboxOption[]>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).
searchDelaynumber
minSearchLengthnumber
searchHintstringWhat the list says before a search can run, and when one fails.
searchFailedTextstring

ComboboxFreeText

PropTypeRequiredDoes
itemsComboboxOption[]Suggestions to filter here. With search they are not needed.
valuestringThe typed text is the value: any text can be kept, and a suggestion only fills it in.
defaultValuestring
onValueChange(text: string) => void
onPick(item: ComboboxOption) => voidA suggestion was picked, for filling the fields that come with it (an institution’s city). It runs after onValueChange, so what it sets stands.
disabledboolean
namestringThe form field name of the hidden input that carries the value.
idstring
labelstringYesThe visible label above the box. Required: a combobox always has one.
placeholderstringAn example only, never the label (patterns.md, "Form").
loadingbooleanThe items are still arriving: the popup says so instead of "no match".
loadingTextstring
helpReactNodeHelp under the label, outside the box; also where a disabled box says why.
errorReactNodeThe error, beside the field: marks the box invalid and describes it.
requiredboolean
containerHTMLElement | nullWhere the popup is portaled. Inside a modal <dialog> pass the dialog, or the popup renders under the top layer, out of sight.
defaultOpenbooleanFor specimens and tests: open on mount, with this text typed.
defaultInputValuestring
search(query: string, signal: AbortSignal) => Promise<ComboboxOption[]>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).
searchDelaynumber
minSearchLengthnumber
searchFailedTextstring

ComboboxMultiple

PropTypeRequiredDoes
valuesstring[]The chosen values, controlled. Leave undefined to let the combobox hold them.
defaultValuesstring[]
onValuesChange(values: string[]) => void
creatablebooleanA 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) => stringThe words of the create row, from the typed text.
labelstringYesThe visible label above the box. Required: a combobox always has one.
itemsComboboxOption[]Yes
placeholderstringAn example only, never the label (patterns.md, "Form").
emptyTextReactNode | ((query: string) => ReactNode)What an empty result says. A function gets the typed text, to name the filter.
loadingbooleanThe items are still arriving: the popup says so instead of "no match".
loadingTextstring
helpReactNodeHelp under the label, outside the box; also where a disabled box says why.
errorReactNodeThe error, beside the field: marks the box invalid and describes it.
disabledboolean
requiredboolean
namestringThe form field name of the hidden input that carries the value.
idstring
containerHTMLElement | nullWhere the popup is portaled. Inside a modal <dialog> pass the dialog, or the popup renders under the top layer, out of sight.
defaultOpenbooleanFor specimens and tests: open on mount, with this text typed.
defaultInputValuestring
search(query: string, signal: AbortSignal) => Promise<ComboboxOption[]>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).
searchDelaynumber
minSearchLengthnumber
searchHintstringWhat the list says before a search can run, and when one fails.
searchFailedTextstring

CSS variables

VariableDefault
--anchor-widthset by the page
--available-heightset by the page
--available-widthset by the page
--listbox-maxmin(22rem, var(--available-height))

Parts and data attributes

ClassIs
.cap-comboboxthe root
.cap-combobox-chipa part
.cap-combobox-chip-removea part
.cap-combobox-chipsa part
.cap-combobox-cleara part
.cap-combobox-emptya part
.cap-combobox-errora part
.cap-combobox-groupa part
.cap-combobox-helpa part
.cap-combobox-inputa part
.cap-combobox-labela part
.cap-combobox-lista part
.cap-combobox-popupa part
.cap-combobox-positionera part
.cap-combobox-statusa part
.cap-combobox-triggera part
AttributeValues
data-disabledpresent or absent
data-emptypresent or absent
data-highlightedpresent or absent
data-popup-openpresent or absent
StateRead from
:disabledthe platform
:emptythe platform
:focus-visiblethe platform
:hoverthe platform
[aria-invalid="true"]an attribute

Accessibility

KeyDoes
ArrowDownOpens the list; then moves the highlight down
ArrowUpMoves the highlight up
TypingFilters the list
EnterChooses the highlighted option and closes the list
EscCloses the list; the box keeps focus and shows the chosen value
TabLeaves 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.