Health
Reference ranges
What a reference range is, who owns it, how opsinjs draws one and what it refuses to draw.
A reference range is a statistical statement about a population, usually built so that a defined majority of an apparently healthy reference group falls inside it. The laboratory, device maker or clinical team that issued it owns it, for its own assay and population, and ranges differ between laboratories for the same test. A value inside it is not proof of health, and one outside it is not disease.
The rules
Show the value, show the range it is compared against, name whose range it is, and never characterise the person.
- The range is attributed where the comparison is made: "your laboratory's usual range", or "the range this device uses".
- The range is shown, not merely applied. Its endpoints sit beside the value.
- A small change near the boundary makes a small change on screen, so "just outside" and "far outside" can be told apart.
- Direction is stated in words, such as "higher than the usual range", not only by a dot's position.
- Nothing asserts a cause. "Higher than the usual range" is an observation, and "You may be dehydrated" is a diagnosis.
- Only a range built for the reader's population is shown, such as "usual range for adults over 18". Where none covers the reader, none is shown.
- The raw value and its unit stay visible beside any gauge, bar or dial.
- No banned word appears in any string about a person's own result.
- With no defensible range, show the value alone and say so. Never invent one from a search result or a textbook.
- Never draw a red-to-green gradient without numbers. It asserts a quality scale that ranges do not have.
- Being outside a range is not automatically
attention. Your product assigns the status. - A composite score with no reference interval discloses that its band names are the product's own.
Banned words
Each describes the person rather than the measurement, or means something else to a lay reader.
| Banned | Use instead |
|---|---|
| normal, abnormal | "in the usual range", "outside the usual range" |
| healthy, unhealthy | "in the usual range", "higher than the usual range" |
| good, bad | The direction, "higher" or "lower" |
| poor, failed | "lower than expected" |
| perfect, optimal | "in the usual range" |
| positive, negative | Name the finding, "X was found" or "X was not found" |
| elevated | "higher than" |
pnpm check fails when one of these, or "just", "don't worry" or "diagnosis" from the full list in tokens/glossary.json, reaches a shipped component. The lint rule opsinjs/no-banned-word is specified and not written, so your own copy is checked in review. Fuller replacements are in the Plain English A to Z.
How opsinjs draws a range
opsinjs ships no reference range, and RangeBar has no default, no population fallback and no range inferred from the reader's history.
<RangeBar
label="Example measurement"
value={14}
unit="mg/dL"
precision={0}
locale="en-GB"
range={{ low: 10, high: 20, source: "Example data rather than a reference range" }}
/>range.sourceis required. A range without one raises OPSIN-0004 and draws nothing, because a plausible band is worse than none.- A range with no bounds, or reversed bounds, is discarded entirely.
- A bar needs two bounds. A one-sided range, such as "up to 20", renders the sentence and no bar.
- An omitted
range.asOfreads as "we do not know", never as today's date. statusis an input and colours only the tick. RangeBar never turns "above the range" into a status, and nothing in it animates.- The summary sentence always renders, even when no bar can be drawn.
Heart. Illustrative only
148 units
Your range: 90 to 130 units
Needs attention. Contact your care team about this reading. It is outside the range they set for you.
The thresholds in this demo are arbitrary and exist only to move the specimen. opsinjs does not own clinical thresholds: they come from the service, a guideline, or the reader’s own clinician, and a design system that shipped defaults for them would be making clinical decisions for every product that installed it.
Demonstration values in these docs are placeholders, not reference ranges, and must never be copied into a product.
Evidence
- The 2024 systematic review of laboratory-result presentation formats in JMIR, 10.2196/53993, examines the formats used to communicate results to patients and their effects on comprehension.
- The 2018 study in BMC Medical Informatics and Decision Making, 10.1186/s12911-018-0589-7, examines patient-portal presentation of results.
Both anchor the claim that presentation format materially changes what a lay reader takes from a number, and that a bare value beside a reference interval suits a lay reader badly. This page extracts no effect size and no recommendation from either. Both are short and are cited to be read rather than summarised. The banned-word list and rule 3 are opinion, and neither paper backs any single rule.