Skip to main content

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​

Storybook
Storybook
Storybook

No Matches​

Storybook

With Error​

Storybook

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​

VariantWhat it is
patientAvatar, name, DOB and MRN per row; flags such as Restricted show as a badge.
codeCode chip then description: "E11.9 Type 2 diabetes mellitus without complications".
no resultsMessage with what to try next.
errorField 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​

PropTypeDefaultDescription
label *string—Visible label; required
kindComboboxKind'plain''patient' (avatar per row) | 'code' (code chip) | 'plain'
options *ComboboxOption[]—Array<{value?, label, meta?, code?, flag?, flagTone?}>; required
placeholderstringnoneExample text in the empty input
querystringundefined (uncontrolled)Controlled query text
defaultQuerystring""Initial query (uncontrolled)
onQueryChange(query: string) => void—Called when the query text changes
openbooleanundefined (uncontrolled)Controlled open state of the list
defaultOpenbooleanfalseOpen on first render (uncontrolled)
onOpenChange(open: boolean) => void—Called when the list opens or closes
onSelect(option: ComboboxOption) => voidnoneCalled with the chosen option
limitnumber8Maximum results shown
emptyTextstring"No matches. Check the spelling or search by MRN."Text when nothing matches
footerReactNodenoneNode under the list ("Search all 4,212 patients")
errorstringnoneError message (as TextField)
helperstringnoneMuted hint under the field
requiredbooleanfalseRed asterisk plus aria-required
styleCSSProperties—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>
KindNameDescription
attributelabelVisible label; required
attributekind'patient' (avatar per row) | 'code' (code chip) | 'plain'; default 'plain'
property / JSON attributeoptionsArray<{value?, label, meta?, code?, flag?, flagTone?}>; required
attributeplaceholderExample text in the empty input; default none
attributequeryControlled query text; default undefined (uncontrolled)
attributedefault-query / defaultQueryInitial query (uncontrolled); default ""
attributeopenControlled open state of the list; default undefined (uncontrolled)
attributedefault-open / defaultOpenOpen on first render (uncontrolled); default false
attributelimitMaximum results shown; default 8
attributeempty-text / emptyTextText when nothing matches; default "No matches. Check the spelling or search by MRN."
attributeerrorError message (as TextField); default none
attributehelperMuted hint under the field; default none
attributerequiredRed asterisk plus aria-required; default false
property / JSON attributestyleInline style of the root
attributedefault-checked / defaultChecked
attributeauto-focus / autoFocus
attributeread-only / readOnly
property / JSON attributetype
attributedisabled
attributename
property / JSON attributemax
property / JSON attributestep
attributeaccept
property / JSON attributeauto-complete / autoComplete
attributechecked
attributemax-length / maxLength
property / JSON attributemin
attributemultiple
eventco-query-changeCalled when the query text changes (React: onQueryChange)
eventco-open-changeCalled when the list opens or closes (React: onOpenChange)
eventco-selectCalled with the chosen option; default none (React: onSelect)
eventco-input (React: onInput)
slotfooterNode under the list ("Search all 4,212 patients"); default none Plain text also works as the `footer` attribute.