Search

Usually the moment a clinician picks a patient — which makes it the most direct route to a wrong-patient error in the whole product, and the reason none of its conveniences are free.

Overview

Consumer search optimises for speed to a result: predictive, forgiving, first-hit-usually-right. Every one of those behaviours is a wrong-patient mechanism when the results are people, and surnames repeat far more often on one ward than designers expect.

So patient search here is deliberately slower: it will not guess, it will not auto-select, and it will not show a result the clinician cannot distinguish from its neighbour.

Anatomy

Behaviour

• Minimum three characters before any patient query runs. Shorter queries return result sets nobody can meaningfully scan.
• Never auto-select, never auto-navigate — not on a single result, not on an exact MRN match. The clinician picks, always.
• Never reorder results while typing. A list that resequences under the pointer causes the same failure as an unstaged queue insertion — see Data grid.
• Debounce, but never drop keystrokes. The query that runs is the query the clinician finished typing.
• Exact MRN matches rank first and are labelled as exact, but are still selected deliberately.
• No fuzzy matching on identifiers. Fuzzy matching on names is helpful; on an MRN it is a mechanism for returning the wrong patient.

No results, and failed search

The same distinction as Empty state, and for the same reason: "this patient is not here" and "the search did not run" must never look alike.

The wording on the failure case is deliberate: "do not conclude the patient is absent". An unavailable search that renders as "no results" is the search equivalent of a failed queue rendering as an empty one.

This page argued that distinction long before the component could express it. totalMatches was a plain number, so a directory that timed out rendered as “0 matching records” — a claim about a patient produced by a network error. It now takes the same Maybe union the rest of the package uses for a quantity it did not compute, which also removed the searching flag: reporting a count while still searching is no longer expressible.

The answer must name its question

Debouncing decides when a query runs. It does nothing about the order the answers come back in. Two requests are in flight; the one for smi is served from a cold index and the one for smith from a warm one, and the slower answer arrives last and wins. The box says smith. The list is the Smiths, the Smitheys and the Smilies.

• The component is given the query its hits answer, not asked to infer it. forQuery is required, so results with no stated question cannot be rendered. Where it differs from what is in the box, the list says so and stays visible — hiding it would throw away work the reader can still use.
• Discarding late answers is the caller's job, and it is not enough. A request that is superseded should be abandoned; the display still has to be honest in the window before that happens, and after a retry, and when two workstation tabs share a session.
• This is not the same rule as “never reorder while typing”. That one is about a list moving under a pointer. This one is about a list that is not the answer to the question on screen, and it survives perfect debouncing.
• The same applies to a retried search. An answer that arrives after the clinician has moved on to another patient is not a result; it is a message from a previous context, and it never replaces the current one.

Non-patient search

Searching documentation, settings or an option list is ordinary search and carries none of the above. It may autocomplete, may highlight a best match, and may act on Enter. The constraints on this page apply specifically where the result set is people, orders or clinical records — the component takes a subjects prop so the distinction is explicit rather than a matter of judgement at each call site.

What the component enforces, and what it only asks for

This is the most consequential page in the package to get this wrong on, because a reader who assumes the component is holding these rules will ship a patient search that does not hold them. It is a controlled component: it has no state, no timer and no knowledge of your index.

Do's and don'ts

Accessibility

• Not a combobox. Results are a named list of real buttons below the field, reached with Tab; each is the whole patient — name, identifier, date of birth — and is focused and read before Enter can select it. The combobox pattern was rejected on purpose: its highlighted-but-unfocused option, moved by arrow and committed by Enter, is the wrong-patient hazard in one keystroke. This bullet used to describe a combobox the component did not ship.
• Result count announced politely on change — "3 results" — never each result individually as the list rebuilds.
• Each result's accessible name carries the distinguishing fields, so a screen-reader user hears the date of birth and MRN rather than a bare name.
• Focus never moves to results automatically. The clinician tabs down when ready.
• type="search" with a visible label, never a placeholder standing in for one.
• Results reachable at 200 % zoom; the list scrolls internally rather than extending past the viewport.

Outcomes of use

What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.

• Effectiveness — the patient opened is the patient intended. This is the component's entire reason for its constraints.
• Efficiency — deliberately traded. Requiring three characters and an explicit selection costs perhaps two seconds, against a wrong-patient event that costs far more.
• Satisfaction — confidence at the moment of selection. A clinician who has to re-check the header after searching has been failed by the search.

Clinical safety notes

• No auto-selection or auto-navigation. (the component) Mitigates: opening a patient nobody chose.
• Date of birth and full MRN on every result. (the component) Mitigates: same-surname mis-selection — the commonest wrong-patient mechanism.
• No fuzzy matching on identifiers. (you) Mitigates: a transposed digit returning a different patient as a near match.
• No browser autofill or autocorrect. (the component) Mitigates: a previous patient suggested into the current query.
• Results never reorder while typing. (you) Mitigates: selecting a row that moved.
• Failure distinguished from no-results. (the component) Mitigates: an unreachable directory read as "this patient does not exist".
• Search scope stated. (you) Mitigates: a site- or admission-limited result set read as exhaustive.
• Recent searches separated and cleared on user switch. (you) Mitigates: acting on the previous clinician's patient.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/search.json

<Search
  label="Find a patient"
  query={query}
  forQuery={answered}        // required: which query these hits answer
  onQueryChange={setQuery}
  totalMatches={{ kind: "value", value: 2 }}
  hits={hits}                // each carries name, identifier and dateOfBirth
  onSelect={open}
/>

// 'totalMatches' is a Maybe, so a search that could not run cannot be
// rendered as a search that found nothing.

What the component takes. This table used to list subjects, minLength, scope, onSearchError — props the component does not have, and never had. Found by the registry gate’s props-table rule.

Related

• Patient header — where a selection lands.
• Text field — identifier input rules.
• Empty state — no-results versus failure.
• Sign in / sign out — clearing recents on user switch.