Global Search
Last Updated: September 2026Global search is the product command palette for jumping to people, records, and actions.
Source CodeAnatomy
link- 1Search input
- 2Group label
- 3Action row
- 4Shortcuts footer
Variants
linkWith trigger
GlobalSearch.Trigger (Modal.Trigger) opens the palette from any button.
Action types
actionType drives the colored prefix: GO_TO, OPEN, TAKE_ACTION, ADD_NOTE_TO.
Loading
loading shows skeleton rows while a query resolves.
Empty
emptyMessage when items are empty and not loading.
With context
context chip narrows search; clear via onContextClear or Backspace on empty input.
Usage Guidelines
linkWhen to use
- •As the product command palette for jumping to people, records, and actions.
- •When grouped recents and results need a dedicated search surface.
- •With a trigger in the app shell (often ⌘K / Ctrl+K).
When not to use
- •For filtering a single table — use an inline Input.
- •For page-local find-in-page — use browser or local search.
- •As permanent navigation chrome — prefer Sidebar.
Control open with open + onOpenChange and pass already-filtered groups.
Don't invent free-form rows — each item needs icon, actionType, and breadcrumbs.
Use caption for secondary metadata (synthetic DOB/id), not for the primary name.
Don't leave GlobalSearch permanently open as nav chrome — use Sidebar.
Behaviors
linkModal + search
- •GlobalSearch extends Modal — use open / onOpenChange (or GlobalSearch.Trigger).
- •items is required: Array<{ label, items: [{ icon, actionType, breadcrumbs, caption? }] }>.
- •Filtering is owned by the consumer — pass already-filtered groups; filter={null} internally.
Search value
- •Controlled: searchValue + onSearchValueChange.
- •Uncontrolled: defaultSearchValue.
- •Selecting a row does not overwrite the query (item-press is ignored for input updates).
Context drill-in
- •context renders a removable chip in the search bar.
- •onContextClear fires on chip click or Backspace when the input is empty.
- •onSettingsClick shows a settings IconButton in the footer when provided.
Content Guidelines
linkGroups and breadcrumbs
- •Group labels should be short section names (Recents, Patients, Claims).
- •Breadcrumbs are a trail after the action label — keep segments short and ordered.
Action types
- •GO_TO / OPEN / TAKE_ACTION / ADD_NOTE_TO map to fixed colored prefixes.
- •Use synthetic names only in demos (Jane Doe is fine as synthetic).
Accessibility
linkText & Labels
- •searchPlaceholder should describe what can be found.
- •emptyMessage should explain that nothing matched.
ARIA attributes
- •Built on Modal (dialog) + Base UI Combobox for list navigation.
- •Highlighted rows show an Enter affordance for keyboard selection.
Keyboard Support
- •Focus lands in the search input when the modal opens.
- •Arrow up/down moves highlight; Enter selects.
- •Escape closes; Backspace on empty input clears context when set.
WCAG Compliance Standards
FAQs
linkWhat shape do items take?
[{ label, items: [{ icon, actionType, breadcrumbs, caption? }] }]. actionType is GO_TO | OPEN | TAKE_ACTION | ADD_NOTE_TO.
How do I control open state?
Pass open and onOpenChange (Modal props), or compose GlobalSearch.Trigger as a child for uncontrolled open from a trigger.
Who filters results?
You do. Wire searchValue / onSearchValueChange and pass filtered groups — GlobalSearch does not filter items itself.