Combobox
BasicInputs
<co-combobox>Combobox is a search field with a result list, for finding a patient or an ICD-10 or CPT code.
import { Combobox } from 'health-components';
Examples
Showcase
Patient Search
Code Search
No Matches
With Error
Usage
<Combobox label="Patient" kind="patient" options={patients.map(p => ({ value: p.id, label: p.name, meta: p.dob + " . " + p.mrn }))} onSelect={openChart} />
<Combobox label="Diagnosis (ICD-10)" kind="code" options={icd10} onSelect={addDx} />
When to use
- Picking from a long list by typing: patients, ICD-10, CPT, payers, pharmacies.
When not to use
- Short fixed lists: Select.
Variants and states
| Variant | What it is |
|---|---|
| patient | Avatar, name, DOB and MRN per row; flags such as Restricted show as a badge. |
| code | Code chip then description: "E11.9 Type 2 diabetes mellitus without complications". |
| no results | Message with what to try next. |
| error | Field error under the input. |
Accessibility
- ARIA combobox pattern: role combobox, aria-expanded, aria-controls, aria-activedescendant; options have role option.
- Arrow keys move, Enter picks, Escape closes.
- A name match is a candidate, not a confirmed patient. Show DOB and MRN in every row so staff confirm identity before opening the chart.
Do and don't
- Do: Show DOB and MRN with every patient result.
- Do: Search ICD-10 by code or by words.
- Don't: Auto-select the first match on blur.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label; required |
kind | ComboboxKind | 'plain' | 'patient' (avatar per row) | 'code' (code chip) | 'plain' |
options * | ComboboxOption[] | — | Array<{value?, label, meta?, code?, flag?, flagTone?}>; required |
placeholder | string | none | Example text in the empty input |
query | string | undefined (uncontrolled) | Controlled query text |
defaultQuery | string | "" | Initial query (uncontrolled) |
onQueryChange | (query: string) => void | — | Called when the query text changes |
open | boolean | undefined (uncontrolled) | Controlled open state of the list |
defaultOpen | boolean | false | Open on first render (uncontrolled) |
onOpenChange | (open: boolean) => void | — | Called when the list opens or closes |
onSelect | (option: ComboboxOption) => void | none | Called with the chosen option |
limit | number | 8 | Maximum results shown |
emptyText | string | "No matches. Check the spelling or search by MRN." | Text when nothing matches |
footer | ReactNode | none | Node under the list ("Search all 4,212 patients") |
error | string | none | Error message (as TextField) |
helper | string | none | Muted hint under the field |
required | boolean | false | Red asterisk plus aria-required |
style | CSSProperties | — | Inline style of the root |
Also accepts native attributes, including defaultChecked, autoFocus, onInput, readOnly, type, disabled, name, max, step, accept, autoComplete, checked, maxLength, min, multiple, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-combobox>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-combobox label="…" kind="…" [options]="options" (co-query-change)="onQueryChange($event.detail)"></co-combobox>
| Kind | Name | Description |
|---|---|---|
| attribute | label | Visible label; required |
| attribute | kind | 'patient' (avatar per row) | 'code' (code chip) | 'plain'; default 'plain' |
| property / JSON attribute | options | Array<{value?, label, meta?, code?, flag?, flagTone?}>; required |
| attribute | placeholder | Example text in the empty input; default none |
| attribute | query | Controlled query text; default undefined (uncontrolled) |
| attribute | default-query / defaultQuery | Initial query (uncontrolled); default "" |
| attribute | open | Controlled open state of the list; default undefined (uncontrolled) |
| attribute | default-open / defaultOpen | Open on first render (uncontrolled); default false |
| attribute | limit | Maximum results shown; default 8 |
| attribute | empty-text / emptyText | Text when nothing matches; default "No matches. Check the spelling or search by MRN." |
| attribute | error | Error message (as TextField); default none |
| attribute | helper | Muted hint under the field; default none |
| attribute | required | Red asterisk plus aria-required; default false |
| property / JSON attribute | style | Inline style of the root |
| attribute | default-checked / defaultChecked | |
| attribute | auto-focus / autoFocus | |
| attribute | read-only / readOnly | |
| property / JSON attribute | type | |
| attribute | disabled | |
| attribute | name | |
| property / JSON attribute | max | |
| property / JSON attribute | step | |
| attribute | accept | |
| property / JSON attribute | auto-complete / autoComplete | |
| attribute | checked | |
| attribute | max-length / maxLength | |
| property / JSON attribute | min | |
| attribute | multiple | |
| event | co-query-change | Called when the query text changes (React: onQueryChange) |
| event | co-open-change | Called when the list opens or closes (React: onOpenChange) |
| event | co-select | Called with the chosen option; default none (React: onSelect) |
| event | co-input | (React: onInput) |
| slot | footer | Node under the list ("Search all 4,212 patients"); default none Plain text also works as the `footer` attribute. |