formstexulinot agent-emittableapp
Combobox
combobox
A text input that filters a list of options, for one value or several.
Live examples
Required form field
Required form field
Loading demo…
Props
| Name | Kind | Required | Default | Description |
|---|---|---|---|---|
value | unknown | no | — | Selected value (a string, or a string array when multiple) |
defaultValue | unknown | no | — | Starting selection; a form reset restores it |
inputValue | string | no | — | Text in the input (bindable) |
defaultInputValue | string | no | "" | — |
items | array | no | — | Options as { value, label, disabled? } |
loadOptions | unknown | no | — | Function prop the host passes: (query, signal) => Promise<items> for remote options. Not agent-emittable (functions are not data). |
filter | unknown | no | — | Function prop the host passes: (item, query) => boolean. Replaces the default match (label contains the query, ignoring case); runs on the trimmed, non-empty query; unused with loadOptions. createFoldedFilter builds an accent-insensitive one. Not agent-emittable (functions are not data). |
multiple | boolean | no | false | — |
disabled | boolean | no | false | Not interactive, not submitted, not validated |
name | string | no | — | Form field name: submits the value (one entry per value when multiple) |
required | boolean | no | false | Blocks form submission until a value is selected |
requiredMessage | string | no | — | Translated message when required blocks submission (default: the browser message) |
form | string | no | — | Associated form id |
open | boolean | no | false | — |
size | enum (sm, md, lg) | no | "md" | — |
variant | enum (outline, soft) | no | "outline" | — |
class | string | no | — | — |
onValueChange | event | no | — | — |
onInputValueChange | event | no | — | — |
onOpenChange | event | no | — | — |
children | slot | no | — | — |
Keyboard
| Key | Action |
|---|---|
Enter, Escape | Arrow keys move, Enter selects, Escape closes; empty, loading and error states are announced |
a | With required, a rejected form moves focus to the input |
Accessibility
- The input keeps focus; aria-activedescendant tracks the highlighted option
- Arrow keys move, Enter selects, Escape closes; empty, loading and error states are announced
- With required, a rejected form moves focus to the input
Evidence for combobox
Latest committed gates for combobox (as of 2026-10-23). Static snapshot — not live CI.
Behavior
checkedscenario combobox
Rows in tests/behavior/scenarios/combobox.spec.ts, held to the WAI-ARIA APG pattern, run on Chromium, WebKit and the Pixel 7.
Size (gzip)
@texuli/primitives/combobox · measured 12.9 KiB · budget 24.0 KiB
Measured gzip from docs/quality/perf-primitives.md (2026-10-23).
Axe
documented
tests/e2e/site-component-pages.spec.tsdocs/quality (a11y-*)
Site component pages axe gate; package-level a11y docs under docs/quality when present.
Browsers
chromiumwebkitmobile
Playwright projects: Desktop Chrome, Desktop Safari, Pixel 7. Firefox is a known gap on this host.
When to use
Use when
- Pick from a long list by typing to filter
- Options loaded from a server as the user types
Don’t use when
Prefer another component
- A short closed list (use select or radio-group)
- Several values shown as chips (use multi-select)