Reference Range

Demos

A result inside its range.

Glucose, fasting

Normal

92mg/dLRef 70–99 mg/dL

Z +1.03

"use client"

import { ReferenceRange } from "@workspace/ui/tools/reference-range"

export function ReferenceRangeDemo() {
  return (
    <div className="mx-auto flex w-full justify-center">
      <ReferenceRange
        name="Glucose, fasting"
        value={92}
        unit="mg/dL"
        range={{ low: 70, high: 99 }}
      />
    </div>
  )
}

Usage

Use a reference range card to show one lab result: the value, its flag, the range printed on the report, and where the value falls. For a full report, put several in a grid.

Import it from @workspace/ui/tools/reference-range.

Anatomy

Header — The test name, an optional longer name, and a flag badge.
Value — The result and its unit, in the status colour.
Range — The reference range as printed on a report, such as Ref 70–99 mg/dL.
Bar — Coloured zones with a marker at the value: normal inside the range, mild outside it, and extreme past a critical limit. Only shown for numbers with a low or high limit. The harmless side of a directional range is grey.
Footer — The Z-score and the direction, when there are any.

Flags

Flag	When
`normal`	Between `low` and `high`, inclusive.
`low`, `high`	Outside `low` or `high`.
`critical-low`, `critical-high`	Below `criticalLow` or above `criticalHigh`. Checked first.
`abnormal`	Only when you pass `flag="abnormal"`, such as a text result that doesn't match.
`unflagged`	A text value, or no `low` or `high`.

Z-score and direction

With both limits, the range is read as the middle 95% of healthy values. The mean is (low + high) / 2, the SD is (high − low) / 4, and Z is (value − mean) / SD. A value inside the range has a |Z| of 2 or less.

range.direction says which way is bad:

Direction	Label	Meaning
`high`	↑ Bad	A raised value is a concern, such as CRP. A low one is not.
`low`	↓ Bad	A lowered value is a concern, such as HDL or vitamin D.
`both`	Normal best	Either side is a concern. The default.
`context`	Context	Either side may matter, depending on the person.

rangeDirectionLabels maps each direction to its label.

Colours

The colour uses the five-step severity scale from globals.css, in the same order as the Bio Clock. Change --status-* in your theme to recolour it.

Result	Colour
In range	`--status-normal`
Out of range, \|Z\| under 3 (or no Z-score)	`--status-mild`
\|Z\| 3 to under 4	`--status-moderate`
\|Z\| 4 to under 5, or `abnormal`	`--status-severe`
\|Z\| 5 or more, or a critical flag	`--status-extreme`
Out of range on the harmless side, or unflagged	Muted

Notes

Limits are inclusive. A glucose of 99 with a high of 99 is normal.
A range with only high prints as ≤ 200, and its bar starts at zero. A range with only low prints as ≥ 30.
range.text replaces the printed range, for results such as Negative. Text values are never flagged on their own, so pass flag yourself.
decimals sets the decimal places for the value and the range.
The card sets data-flag and data-tone, for styling or tests.

Reference range helpers

The flagging logic is in @workspace/ui/lib/reference-range, so you can use it without the UI.

rangeTone(flag, z, direction) from the component file returns the status colour the card uses, as a RangeTone: normal, mild, moderate, severe, extreme, or none.

Examples

Flags

Low, high, critical, a lower limit only, a text result, and a result with no range.

Haemoglobin

Low

11.2g/dLRef 12.0–15.5 g/dL

Z -2.91

Total cholesterol

High

232mg/dLRef ≤ 200 mg/dL

Potassium

Critical high

6.8mmol/LRef 3.5–5.1 mmol/L

Z +6.25

Vitamin D

Normal

34ng/mLRef ≥ 30 ng/mL

Urine protein

Abnormal

PositiveRef Negative

Blood group

Not flagged

O+

"use client"

import { ReferenceRange } from "@workspace/ui/tools/reference-range"

export function ReferenceRangeFlags() {
  return (
    <div className="mx-auto grid w-full max-w-3xl gap-3 sm:grid-cols-2">
      <ReferenceRange
        name="Haemoglobin"
        value={11.2}
        unit="g/dL"
        decimals={1}
        range={{ low: 12, high: 15.5 }}
      />
      <ReferenceRange
        name="Total cholesterol"
        value={232}
        unit="mg/dL"
        range={{ high: 200 }}
      />
      <ReferenceRange
        name="Potassium"
        value={6.8}
        unit="mmol/L"
        decimals={1}
        range={{ low: 3.5, high: 5.1, criticalLow: 2.8, criticalHigh: 6.2 }}
      />
      <ReferenceRange
        name="Vitamin D"
        value={34}
        unit="ng/mL"
        range={{ low: 30 }}
      />
      <ReferenceRange
        name="Urine protein"
        value="Positive"
        range={{ text: "Negative" }}
        flag="abnormal"
      />
      <ReferenceRange name="Blood group" value="O+" />
    </div>
  )
}

Interactive

Change the value to see the flag and the marker move. Potassium has critical limits at 2.8 and 6.2 mmol/L.

Potassium (mmol/L)

Potassium

Normal

4.2mmol/LRef 3.5–5.1 mmol/L

Z -0.25

"use client"

import * as React from "react"

import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
  NumberFieldScrubArea,
} from "@workspace/ui/components/number-field"
import { ReferenceRange } from "@workspace/ui/tools/reference-range"

export function ReferenceRangeInteractive() {
  const [value, setValue] = React.useState<number | null>(4.2)

  return (
    <div className="mx-auto flex w-full max-w-sm flex-col gap-3">
      <NumberField
        value={value}
        onValueChange={setValue}
        step={0.1}
        format={{ minimumFractionDigits: 1, maximumFractionDigits: 1 }}
      >
        <NumberFieldScrubArea label="Potassium (mmol/L)" />
        <NumberFieldGroup>
          <NumberFieldDecrement />
          <NumberFieldInput />
          <NumberFieldIncrement />
        </NumberFieldGroup>
      </NumberField>
      <ReferenceRange
        name="Potassium"
        value={value ?? Number.NaN}
        unit="mmol/L"
        decimals={1}
        range={{ low: 3.5, high: 5.1, criticalLow: 2.8, criticalHigh: 6.2 }}
      />
    </div>
  )
}

Biomarker panel

Forty example biomarkers, each with a direction. Most are out of range, so the colours step up with |Z|. CRP at 4.2 is inside its range, so it stays green even with a Z of +1.42.

hs-CRP

High-sensitivity C-reactive protein

High

3.5mg·L⁻¹Ref 0.2–3 mg·L⁻¹

Z +2.71↑ Bad

CRP

C-reactive protein

Normal

4.2mg·L⁻¹Ref 0.1–4.9 mg·L⁻¹

Z +1.42↑ Bad

NLR

Neutrophil-to-lymphocyte ratio

High

3.2Ref 1–3

Z +2.40↑ Bad

IL-6

Interleukin-6

High

9.8pg·mL⁻¹Ref 0.5–7 pg·mL⁻¹

Z +3.72↑ Bad

TNF-α

Tumor necrosis factor-α

High

12.7pg·mL⁻¹Ref 1–8 pg·mL⁻¹

Z +4.69↑ Bad

CK-MM

Creatine kinase, muscle isoenzyme

High

190U·L⁻¹Ref 50–170 U·L⁻¹

Z +2.67↑ Bad

Aldolase A

High

8.5U·L⁻¹Ref 1.2–7.5 U·L⁻¹

Z +2.63↑ Bad

IGF-1

Insulin-like growth factor-1

Low

82.8ng·mL⁻¹Ref 90–360 ng·mL⁻¹

Z -2.11↓ Bad

Myostatin

High

18.3ng·mL⁻¹Ref 2–12 ng·mL⁻¹

Z +4.52↑ Bad

MMP-9

Matrix metalloproteinase-9

High

155.8ng·mL⁻¹Ref 20–140 ng·mL⁻¹

Z +2.53↑ Bad

CTX-II

C-terminal cross-linked telopeptide of type II collagen

High

510.7pg·mL⁻¹Ref 120–450 pg·mL⁻¹

Z +2.74↑ Bad

PTH

Parathyroid hormone

High

75.3pg·mL⁻¹Ref 15–65 pg·mL⁻¹

Z +2.82↑ Bad

Ca/P ratio

Calcium-to-phosphorus ratio

High

2.9Ref 2–2.8

Z +2.50Normal best

Vitamin D

25-hydroxyvitamin D

Low

25.4ng·mL⁻¹Ref 30–100 ng·mL⁻¹

Z -2.26↓ Bad

Osteocalcin

Low

8.9ng·mL⁻¹Ref 11–43 ng·mL⁻¹

Z -2.26↓ Bad

PINP

Procollagen type I N-terminal propeptide

Low

9.7ng·mL⁻¹Ref 20–80 ng·mL⁻¹

Z -2.69↓ Bad

FBS

Fasting blood sugar

High

110mg·dL⁻¹Ref 70–99 mg·dL⁻¹

Z +3.52↑ Bad

FSI

Fasting serum insulin

High

28.8µIU·mL⁻¹Ref 2–20 µIU·mL⁻¹

Z +3.96↑ Bad

HbA1c

Glycated hemoglobin

High

7.6%Ref 4–5.6 %

Z +7.00↑ Bad

Total cholesterol

High

225.6mg·dL⁻¹Ref 120–199 mg·dL⁻¹

Z +3.35↑ Bad

LDL-C

Low-density lipoprotein cholesterol

High

185.5mg·dL⁻¹Ref 50–99 mg·dL⁻¹

Z +9.06↑ Bad

HDL-C

High-density lipoprotein cholesterol

Low

35.7mg·dL⁻¹Ref 40–80 mg·dL⁻¹

Z -2.43↓ Bad

Triglycerides

High

165.8mg·dL⁻¹Ref 50–149 mg·dL⁻¹

Z +2.68↑ Bad

BDNF

Brain-derived neurotrophic factor

Low

12.8ng·mL⁻¹Ref 15–40 ng·mL⁻¹

Z -2.35↓ Bad

VEGF

Vascular endothelial growth factor

High

305.6pg·mL⁻¹Ref 30–250 pg·mL⁻¹

Z +3.01Context

NOx

Nitric oxide metabolites (nitrate + nitrite)

Low

18.9µmol·L⁻¹Ref 20–60 µmol·L⁻¹

Z -2.11↓ Bad

NGF

Nerve growth factor

Low

18.8pg·mL⁻¹Ref 20–80 pg·mL⁻¹

Z -2.08↓ Bad

Substance P

High

225.6pg·mL⁻¹Ref 30–200 pg·mL⁻¹

Z +2.60↑ Bad

GFAP

Glial fibrillary acidic protein

High

125.7pg·mL⁻¹Ref 20–120 pg·mL⁻¹

Z +2.23↑ Bad

ET-1

Endothelin-1

High

4.6pg·mL⁻¹Ref 0.5–3 pg·mL⁻¹

Z +4.56↑ Bad

MDA

Malondialdehyde

High

4.6µmol·L⁻¹Ref 1–3.5 µmol·L⁻¹

Z +3.76↑ Bad

TGF-β1

Transforming growth factor-β1

High

12.7ng·mL⁻¹Ref 1–8 ng·mL⁻¹

Z +4.69↑ Bad

TIMP-1

Tissue inhibitor of metalloproteinase-1

Low

55.9ng·mL⁻¹Ref 60–180 ng·mL⁻¹

Z -2.14↓ Bad

eGFR

Estimated glomerular filtration rate

Low

82.7mL·min⁻¹·1.73 m⁻²Ref 90–120 mL·min⁻¹·1.73 m⁻²

Z -2.97↓ Bad

Creatinine, serum

High

1.8mg·dL⁻¹Ref 0.7–1.3 mg·dL⁻¹

Z +5.33↑ Bad

BUN

Blood urea nitrogen

High

21.8mg·dL⁻¹Ref 7–20 mg·dL⁻¹

Z +2.55↑ Bad

Uric acid

High

8.9mg·dL⁻¹Ref 3.5–7.2 mg·dL⁻¹

Z +3.84↑ Bad

Urea

Serum urea

High

45.6mg·dL⁻¹Ref 15–40 mg·dL⁻¹

Z +2.90↑ Bad

ALB

Serum albumin

Low

2.8g·dL⁻¹Ref 3.5–5 g·dL⁻¹

Z -3.87↓ Bad

COMP

Cartilage oligomeric matrix protein

High

850ng·mL⁻¹Ref 200–600 ng·mL⁻¹

Z +4.50↑ Bad

"use client"

import { biomarkerRange, biomarkers } from "@workspace/ui/lib/biomarkers"
import { ReferenceRange } from "@workspace/ui/tools/reference-range"

// Example results, by biomarker id.
const results: Record<string, number> = {
  "hs-crp": 3.5, crp: 4.2, nlr: 3.2, "il-6": 9.8, "tnf-alpha": 12.7,
  "ck-mm": 190, "aldolase-a": 8.5, "igf-1": 82.8, myostatin: 18.3,
  "mmp-9": 155.8, "ctx-ii": 510.7, pth: 75.3, "ca-p-ratio": 2.9,
  "vitamin-d": 25.4, osteocalcin: 8.9, pinp: 9.7, fbs: 110, fsi: 28.8,
  hba1c: 7.6, "total-cholesterol": 225.6, "ldl-c": 185.5, "hdl-c": 35.7,
  triglycerides: 165.8, bdnf: 12.8, vegf: 305.6, nox: 18.9, ngf: 18.8,
  "substance-p": 225.6, gfap: 125.7, "et-1": 4.6, mda: 4.6,
  "tgf-beta1": 12.7, "timp-1": 55.9, egfr: 82.7, creatinine: 1.8,
  bun: 21.8, "uric-acid": 8.9, urea: 45.6, albumin: 2.8, comp: 850,
}

export function ReferenceRangePanel() {
  return (
    <div className="mx-auto grid w-full gap-3 sm:grid-cols-2 lg:grid-cols-3">
      {biomarkers.map((biomarker) => (
        <ReferenceRange
          key={biomarker.id}
          name={biomarker.abbreviation}
          description={biomarker.name}
          value={results[biomarker.id] ?? Number.NaN}
          unit={biomarker.unit}
          range={biomarkerRange(biomarker)}
          className="max-w-none"
        />
      ))}
    </div>
  )
}

Props

Unlisted props pass through to the Card that wraps the result.

ReferenceRange

Prop	Type	Default	Description
`name`	`string`	—	The test name, such as `Glucose` or `hs-CRP`.
`description`	`string`	—	A longer name under the title.
`value`	`number or string`	—	The result.
`unit`	`string`	—	Unit shown after the value and the range.
`range`	`ReferenceRange`	—	The limits to flag against.
`decimals`	`number`	—	Decimal places for the value and the range.
`flag`	`RangeFlag`	computed	Overrides the flag.
`className`	`string`	—	Classes merged onto the card.

ReferenceRange (type)

Field	Type	Description
`low`	`number`	Lowest normal value, inclusive.
`high`	`number`	Highest normal value, inclusive.
`criticalLow`	`number`	Values below this are critical low.
`criticalHigh`	`number`	Values above this are critical high.
`text`	`string`	Shown instead of the generated range, such as `Negative`.
`direction`	`"high", "low", "both", or "context"`	Which way is bad. Defaults to `both`.