Text field

Where a clinician types something that will end up in a patient's record. Its boundary must be findable, its label must be permanent, and its errors must never destroy what was entered.

Overview

Text input is where the most ordinary-looking accessibility failures do the most clinical damage. A placeholder used as a label vanishes the moment someone types. A 1.1:1 border makes the field itself hard to locate. An error that clears the input costs a clinician the measurement they just read off a monitor.

None of those are edge cases — they are the default behaviour of most component libraries, including stock shadcn's border treatment. This component fixes them and the token gate keeps them fixed.

Anatomy

Labels, not placeholders

Placeholders may be used for examples of format — e.g. 1964-03-11 — never for the name of the field, and never as the only statement of a required unit.

Validation

• Validate on blur, not on keystroke. Flagging "invalid" while someone is halfway through typing an MRN is noise that trains people to ignore the error state.
• Never clear, truncate or reformat the user's input on error. A field that empties itself costs a value the clinician may have read once off a monitor.
• Errors name the fix. "MRN must be 9 digits — 7 entered. Check the wristband and re-enter", not "Invalid input".
• Never block submission silently. If a form cannot submit, say which field and move focus there.
• Warnings are not errors. A physiologically unusual but possible value gets a confirmation, not a rejection — the patient may genuinely have a troponin of 25 000.

Clinical input rules

States

Read-only and disabled are different. Read-only is a value the clinician may read and copy but not change — model version, acquisition time. Disabled is an input that is not currently applicable, and it always carries adjacent text saying what would make it applicable. A disabled field with no explanation is a dead end.

Do's and don'ts

Accessibility

• Every field has a <label for>. aria-label is a fallback for genuinely label-less controls, not a shortcut.
• Hints and errors are wired with aria-describedby so they are announced with the field, not stranded visually beside it.
• aria-invalid on error, alongside the 2 px border and the message. Three channels, no reliance on colour.
• Focus ring at ≥ 3:1 against both the field and the surface behind it. Never outline: none.
• 44 px minimum height and 16 px text. Meets the touch floor and prevents mobile zoom-on-focus.
• Correct inputmode so a numeric keypad appears on touch — without using type="number", whose spinners and scroll-wheel behaviour cause silent value changes.
• Errors announced politely on blur, never assertively on every keystroke.

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 value recorded matches the value intended — correct units, nothing truncated, no autofill substitution from another patient.
• Efficiency — Entry time, and re-entry rate after validation. A field that clears itself on error doubles the cost of every mistake.
• Satisfaction — Confidence that what was typed was accepted as typed. Silent reformatting erodes this faster than an explicit rejection does.

Clinical safety notes

• Visible boundary at ≥ 3:1, governed. Mitigates: entering data into the wrong field, or failing to find one.
• Permanent labels and units. Mitigates: an unlabelled or unit-less value entering the record.
• Input never cleared or reformatted on error. Mitigates: loss of a value read once from a device.
• Out-of-range confirms rather than rejects. Mitigates: a true extreme value being made un-enterable.
• No autofill on patient identifiers. Mitigates: wrong-patient data entry from a suggestion.
• No type="number". Mitigates: silent value change from a scroll wheel or stray spinner press.
• Disabled fields explain themselves. Mitigates: a clinician unable to proceed and unable to see why.
• ISO dates with visible format. Mitigates: day/month transposition.

Implementation

$ npx shadcn@latest add https://md.notjustany.tech/r/text-field.json

// Label, hint and error wiring is done by the component — the ids and
// aria-describedby cannot be forgotten at the call site.
<TextField
  label="Peak troponin"
  hint="ng/L. Leave blank if not yet resulted."
  inputMode="numeric"
  value={value}
  onChange={setValue}
  onBlur={validate}
  error={error}                 // sets aria-invalid + replaces hint
/>

// Patient identifier — autofill and correction disabled.
<TextField
  label="Patient identifier"
  variant="identifier"   // mono, autocomplete/correct/spellcheck off
  hint="9 digits, as printed on the wristband"
/>

Related

• Sign in / sign out — credential fields and paste.
• Clinician override — the optional free-text reason.
• Tokens — why --input is governed.
• Typography — identifiers and units.