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.

Requiredness is stated in words, not in an asterisk. The asterisk is the near-universal convention and it is learned rather than self-explanatory: it needs a legend somewhere on the page, it is frequently outside the accessible name so it is never announced, and at 12 px it is a hard target for anyone who does not already know what it means. The component writes (required) beside the label and sets required on the input; nothing depends on the reader having been told what a star is.

Where nearly every field on a form is required, marking each one is noise that stops being read. Mark the exceptions instead — (optional) — and say at the top of the form which convention is in use. What is never acceptable is marking neither and letting the reader discover requiredness by being rejected at submit.

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.

This component rendered {error ?? hint} into a single element until this section was written — one message, one id, the hint destroyed on error. It looked correct because the error strings on this page all restate the format themselves; nothing required them to, and error="Invalid" would have lost it entirely.

• Both are named in aria-describedby, error first. The order of that list is announcement order and it is independent of DOM order — so the error is spoken first while the hint keeps a fixed position on screen.
• The hint does not move when an error appears. Inserting the error above it would shift a line the reader may be mid-way through reading. It is appended below.
• Neither is a title attribute or a tooltip. Format requirements that appear on hover are unavailable to touch, to keyboard, and to anyone reading with the field already focused — see Perceivable affordance.
• Clearing the error does not clear the hint, and clearing the field does not clear the error until the value is valid. An error that vanishes on the first keystroke was never read.

What an empty field means

The Date & time picker rejects the standard instruction “leave blank if the date is unknown”, for one reason: a blank records nothing about why it is blank. That argument has nothing to do with dates. It is about blanks, and it applies to every field on this page.

An empty field on a form has at least five readings, and nothing downstream can tell them apart:

The reader who later sees the gap will supply one of those five from context, and they have no way to know which. A troponin that was never ordered and a troponin still in the analyser look identical, and only one of them means somebody should wait.

• Making the field required does not fix it — it makes it worse. Forcing a value out of someone who does not have one produces a value that is wrong rather than missing, and a wrong number is acted on where a gap would have been questioned. Requiredness is for fields that always have an answer.
• The options are clinical, not technical. “Not resulted”, “not applicable” and “patient declined” are different facts about the patient. A single “unknown” collapses them, and a null collapses them further.
• Where the vocabulary genuinely cannot be extended — a field on a form this system does not own — the interface states what the blank is not evidence of, next to the blank, rather than letting the reader assume.
• Never write a hint that assigns a meaning to empty. “Leave blank if not yet resulted” instructs the reader to encode a fact in a place that cannot hold one. This page carried exactly that hint until it was found by comparison with the date picker; it is recorded here rather than quietly removed.

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.

What the component enforces, and what it only asks for

The wiring is held here; the judgement is not. Everything about ids, labels and announcement order is the component's, and everything about when a value is wrong is yours.

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. (the component) Mitigates: entering data into the wrong field, or failing to find one.
• Permanent labels and units. (the component) Mitigates: an unlabelled or unit-less value entering the record.
• Input never cleared or reformatted on error. (the component rewrites nothing; your handler must not either) Mitigates: loss of a value read once from a device.
• Out-of-range confirms rather than rejects. (you) Mitigates: a true extreme value being made un-enterable.
• No autofill on patient identifiers. (you) Mitigates: wrong-patient data entry from a suggestion.
• No type="number". (you) Mitigates: silent value change from a scroll wheel or stray spinner press.
• Disabled fields explain themselves. (you) Mitigates: a clinician unable to proceed and unable to see why.
• ISO dates with visible format. (you) Mitigates: day/month transposition.

Implementation

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

<TextField
  label= "Peak troponin" 
  unit= "ng/L" 
  hint= "If it has not resulted, say so — do not leave blank." 
  inputMode= "decimal" 
  value={value}
  onChange={setValue}
  onBlur={validate}
  error={error}     // added below the hint, never in place of it
/>

// 'placeholder' is omitted from the prop type, so a label that disappears
// when the field is used cannot be written.

What the component takes. This table used to list variant — a prop the component does not have, and never had. Found by the registry gate’s props-table rule.

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.