CommandPalette
ComplexNavigation
<co-command-palette>CommandPalette is the Command Bar style's "Jump to anything" search for screens, patients and actions, opened with Ctrl K or Cmd K.
import { CommandPalette } from 'health-components';
Examples
Filtered
No Results
Open With Shortcut
Usage
{open && <CommandPalette items={searchIndex} onSelect={go} onClose={() => setOpen(false)} />} // open on Ctrl K / Cmd K
const [open, setOpen] = useState(false);
useCommandPaletteShortcut(() => setOpen(true)); // Ctrl K / Cmd K
<CommandPalette open={open} items={searchIndex} onSelect={go} onClose={() => setOpen(false)} />
When to use
- Command Bar style, and as a shortcut in every style.
When not to use
- Patient search inside a form: Combobox.
Variants and states
| Variant | What it is |
|---|---|
| results | Kind pill (Screen, Patient, Action), icon, label, meta. |
| active row | primary-soft. |
| no results | Suggests what to type. |
Accessibility
- combobox with listbox; arrows, Enter, Escape. Key hints in the footer.
Do and don't
- Do: Return patients with DOB and MRN in meta.
- Don't: Run destructive actions straight from the palette without a confirm.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items * | T[] | — | The search index. Required. |
open | boolean | true | Whether the palette is shown |
query | string | uncontrolled | Query (controlled) |
defaultQuery | string | "" | Initial query when uncontrolled |
onQueryChange | (query: string) => void | none | Called on every keystroke |
placeholder | string | "Jump to a screen, patient or action" | Input placeholder and accessible name |
onSelect | (item: T) => void | none | Called with the chosen item (Enter or click) |
onClose | () => void | none | Called on Escape and a scrim press |
maxResults | number | 9 | Most results shown |
inline | boolean | false | Render in place for docs: no portal, focus trap, scroll lock or Escape |
ref | Ref<HTMLDivElement> | — |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, onChange, onInput, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-command-palette>. 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-command-palette open query="…" [items]="items" (co-query-change)="onQueryChange($event.detail)"></co-command-palette>
| Kind | Name | Description |
|---|---|---|
| property / JSON attribute | items | The search index. Required. |
| attribute | open | Whether the palette is shown; default true |
| attribute | query | Query (controlled); default uncontrolled |
| attribute | default-query / defaultQuery | Initial query when uncontrolled; default "" |
| attribute | placeholder | Input placeholder and accessible name; default "Jump to a screen, patient or action" |
| attribute | max-results / maxResults | Most results shown; default 9 |
| attribute | inline | Render in place for docs: no portal, focus trap, scroll lock or Escape; default false |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| property / JSON attribute | ref | |
| event | co-query-change | Called on every keystroke; default none (React: onQueryChange) |
| event | co-select | Called with the chosen item (Enter or click); default none (React: onSelect) |
| event | co-close | Called on Escape and a scrim press; default none (React: onClose) |
| event | co-change | (React: onChange) |
| event | co-input | (React: onInput) |