Skip to main content

ClinicalValue

ComplexClinical values<co-clinical-value>

ClinicalValue shows one clinical measurement with its unit, fixed precision, abnormal flag, trend and reference range, formatted by the shared CareOS.fmt rules.

import { ClinicalValue } from 'health-components';

Examples​

Vitals​

Storybook

Every Flag​

Storybook

With Meta​

Storybook

Range Contexts​

Storybook

Paediatrics And States​

Storybook

Usage​

<ClinicalValue measure="potassium" value={5.4} trend="up" delta="+0.6"
timestamp="2026-10-09T13:40:00Z" timeZone="America/Chicago" source="Quest" showMeta />

When to use​

  • Any vital sign, lab result or score shown on a screen: banner, flowsheet, result inbox, chart summary, mobile.
  • Inside DataTable cells, StatCards and VitalsPanel tiles.

When not to use​

  • Medication doses: use DoseDisplay (different trailing-zero rule).
  • Money: MoneyDisplay. Dates and ages: DateTimeClinical.
  • Free-text or coded results (Positive, Detected): show text with AbnormalFlag A.

Variants and states​

VariantWhat it is
normalValue and unit; no flag unless showNormal.
L / HAmber value with L or H flag.
LL / HHRed value with a solid critical flag that spells out Critical low or Critical high.
AAbnormal without direction, passed as flag.
trendUp, down or unchanged arrow with optional delta.
showMetaSecond line with range, time and source.
entered-in-errorStruck through, grey, unflagged, labelled.
sizessm, md (default), lg.
rangeContextOutpatient, inpatient, ED, pediatric or pregnancy range from the shared registry; a lab range on the result wins.

Accessibility​

  • The value, unit and flag are read as one sentence ("Potassium 5.4 mmol/L, High"); the visual parts are aria-hidden.
  • The range tooltip opens on focus as well as hover.
  • Flags carry letter, icon and word; colour is never the only signal.
  • Trend arrows have a text equivalent (rising, falling, unchanged).

Do and don't​

  • Do: Pass the lab range from the result when you have it.
  • Do: Keep 37.0 °C: the trailing zero is the precision.
  • Don't: Round in the caller and pass a string; pass value and let fmt round.
  • Don't: Hide an entered-in-error result; strike it through.

Clinical value rules​

Every clinical number in CareOS goes through CareOS.fmt. Components never call toFixed or build a unit string themselves. This is what makes a potassium of 5.4 look the same in the banner, the flowsheet, the result inbox and the mobile app.

  1. Tabular figures. Numbers use font-variant-numeric: tabular-nums so columns line up.
  2. Unit always shown. Data keeps the UCUM code (mm[Hg], Cel, 10*3/uL); the screen shows the readable label (mmHg, °C, K/µL). A value with no unit is a bug.
  3. Precision belongs to the measure. Each measure has one number of decimals, applied by rounding half away from zero. Lab and vital values keep trailing zeros at that precision (temperature 37.0 °C) because the precision itself carries meaning.
  4. Doses follow ISMP. Doses are the exception to rule 3: never a trailing zero (5 mg, not 5.0 mg), always a leading zero (0.5 mg, not .5 mg), "units" never "U" or "IU", "mcg" never "µg", "mL" never "cc", commas from 1,000. Look-alike drug names use tall-man lettering (hydrOXYzine, hydrALAZINE).
  5. Flags are never colour alone. Every flag shows a letter (N, L, H, LL, HH, A), an icon and a screen-reader word. Critical flags also show the word on screen.
  6. Critical thresholds use strict comparison. A value flags LL only when it is below critLow and HH only when it is above critHigh. A lab that defines critical as "at or below" must send its own flag.
  7. The range travels with the value. Hover or focus shows the reference range, LOINC code, time and source. When a value is converted to another unit, the range converts with it.
  8. Entered in error stays visible. The number is struck through, greyed, never flagged and labelled "Entered in error". It is never silently removed.
  9. Negative money uses parentheses: ($45.00). Dates are MM/DD/YYYY; times are 12-hour by default with a 24-hour option, and show the zone when one is passed.

Precision per measure​

Decimals and display unit per measure. Ranges are not in this table: every set reads them from one registry, described below.

MeasureLOINCUnit shownDecimalsPaediatric note
Systolic BP8480-6mmHg0Age and height percentiles under 13 y
Diastolic BP8462-4mmHg0
Heart rate8867-4bpm0Newborn 100-160
Respiratory rate9279-1breaths/min0Newborn 30-60
Temperature8310-5°C (°F)1
SpO259408-5%0COPD targets set per patient
Weight29463-7kg (lb)1Infants under 10 kg: 2 decimals
Height8302-2cm (in)1
BMI39156-5kg/m²1Under 20 y: BMI-for-age percentile
Pain score72514-3/100FLACC or Wong-Baker in young children
Glucose2345-7mg/dL (mmol/L, 1 dp)0
Potassium2823-3mmol/L1Newborn upper limit about 6.0
Sodium2951-2mmol/L0
Creatinine2160-0mg/dL (µmol/L, 0 dp)2Much lower in children
eGFR98979-8mL/min/1.73m²0Not reported under 18 y by most labs
Hemoglobin A1c4548-4% (mmol/mol, 0 dp)1
INR6301-6INR1On warfarin the target replaces the range
Hemoglobin718-7g/dL1Adult female 11.6-15.0
WBC6690-2K/µL1
Platelets777-3K/µL0
LDL cholesterol13457-7mg/dL0
TSH3016-3mIU/L2
Troponin I, high sensitivity89579-7ng/L0Cut-off is assay specific

The reference ranges for these measures are in the next section, Reference ranges and flags.

Conversion factors​

ConversionFormulaBasis
lb to kg× 0.45359237Exact by definition
in to cm× 2.54Exact by definition
°F to °C(F − 32) × 5/9Exact
Glucose mg/dL to mmol/L÷ 18.016From molar mass 180.16 g/mol
Creatinine mg/dL to µmol/L× 88.42From molar mass 113.12 g/mol
A1c % to mmol/mol(% − 2.15) × 10.929IFCC master equation

Conversion happens on the stored number, never on the rounded display. Converting 154.3 lb back and forth never drifts.

Age display​

Under 14 days in days (8 d), under 8 weeks in weeks (6 wk), under 24 months in months (9 mo), then years (47 y). Gestational age shows as 38w 4d, from weeks and days or from the EDD.

Reference ranges and flags​

Every CareOS set reads reference ranges from one registry, CareOS.fmt.RANGES, and flags through one function, CareOS.fmt.flag(value, measure, {context, refLow, refHigh}). The same value in the same context gets the same flag on the ED board, the inpatient census, the nursing flowsheet, the chart panels, the specialty screens and ClinicalValue. build/probe_values.js checks this on every build.

Every range in the registry is a sample value, not clinical guidance. Each entry carries source: 'sample value, not clinical guidance'. A deployment replaces the registry with its own reviewed ranges or, better, passes the performing lab's range on each result.

Which range wins​

  1. The lab range on the result. refLow / refHigh passed with the value (FHIR Observation.referenceRange) replace the registry's reference edges in every context. Lab critLow / critHigh replace the registry's critical edges when passed; otherwise the context's critical edges still apply.
  2. The component's rangeContext prop. Every complex component in the inpatient, ED, specialty and chart panel sets, and ClinicalValue, ReferenceRangeBar and UnitToggle, take rangeContext. It reaches every value inside the component. CareOS.RangeContext.Provider does the same for a whole subtree.
  3. The global setting. CareOS.setRangeContext('outpatient' | 'inpatient' | 'ed' | 'pediatric' | 'pregnancy') sets the context for the whole app and re-renders every value. CareOS.setRangeContext(null) clears it.
  4. The set's default. ED and perioperative parts default to ed; inpatient flow and inpatient nursing parts default to inpatient; PrenatalFlowsheet defaults to pregnancy. The others have no default.
  5. Outpatient adult, when nothing above applies.

A context a measure does not define falls back to outpatient. The ed context therefore equals outpatient adult for every measure except temperature, where it uses the fever cut-off of 38.0 °C. The pediatric context picks the band by ageYears; with no age it uses the oldest band, so a missing age never applies an infant's range to a teenager. No set passes an age today, so pediatric bands only apply where a caller passes ageYears to CareOS.fmt.flag or ClinicalValue.

The precedence of the set default under the global setting is a design choice: an app that calls setRangeContext controls every screen, and a screen that needs a different context says so with the prop.

Sample ranges​

Reference edges, with critical edges in parentheses. A value flags L or H when it is strictly outside the reference edges and LL or HH when it is strictly outside the critical edges. Units are the measure's display unit.

Measure keyOutpatient (default adult)InpatientEDPediatric (age bands)Pregnancy
bpSys90-129 (crit <70, >180)90-139 (crit <70, >180)as outpatient1-12 y: 85-115 (crit <60, >140); 13-17 y: 90-129 (crit <70, >160)90-139 (crit <70, >159)
bpDia60-79 (crit <40, >120)60-89 (crit <40, >120)as outpatient1-12 y: 50-75 (crit <35, >100); 13-17 y: 60-79 (crit <40, >110)60-89 (crit <40, >109)
map65-110 (crit <55, >130)as outpatientas outpatientas outpatientas outpatient
hr60-100 (crit <40, >150)as outpatientas outpatientunder 1 y: 100-160 (crit <80, >200); 1-5 y: 80-140 (crit <60, >180); 6-12 y: 70-120 (crit <50, >160); 13-17 y: 60-100 (crit <40, >150)60-110 (crit <40, >150)
rr12-20 (crit <8, >30)as outpatientas outpatientunder 1 y: 30-60 (crit <20, >70); 1-5 y: 24-40 (crit <16, >50); 6-12 y: 18-30 (crit <12, >40); 13-17 y: 12-20 (crit <8, >30)as outpatient
temp36.1-37.2 (crit <35, >40)36.1-37.9 (crit <35, >40)36.1-37.9 (crit <35, >40)as outpatientas outpatient
spo295-100 (crit <88)92-100 (crit <88)as outpatientas outpatientas outpatient
etco235-45 (crit <25, >60)as outpatientas outpatientas outpatientas outpatient
gcs15-15 (crit <9)as outpatientas outpatientas outpatientas outpatient
bmi18.5-24.9as outpatientas outpatientas outpatientas outpatient
pain0-3as outpatientas outpatientas outpatientas outpatient
glucose70-99 (crit <54, >400)70-180 (crit <54, >400)as outpatientunder 1 month: 50-99 (crit <40, >300); 1 month-17 y: 70-99 (crit <54, >400)70-94 (crit <54, >400)
potassium3.5-5.1 (crit <2.8, >6.2)as outpatientas outpatientunder 1 month: 3.7-5.9 (crit <2.8, >7); 1 month-17 y: 3.4-4.7 (crit <2.8, >6)as outpatient
sodium136-145 (crit <120, >160)as outpatientas outpatientas outpatientas outpatient
chloride98-107as outpatientas outpatientas outpatientas outpatient
bicarbonate22-29 (crit <10, >40)as outpatientas outpatientas outpatientas outpatient
bun7-20as outpatientas outpatientas outpatientas outpatient
creatinine0.74-1.35as outpatientas outpatient1-5 y: 0.2-0.5; 6-12 y: 0.3-0.7; 13-17 y: 0.5-10.4-0.8
egfr≥60as outpatientas outpatientas outpatientas outpatient
calcium8.6-10.3 (crit <6, >13)as outpatientas outpatientas outpatientas outpatient
magnesium1.7-2.2 (crit <1, >4.9)as outpatientas outpatientas outpatientas outpatient
a1c4-5.6as outpatientas outpatientas outpatientas outpatient
ldl≤99as outpatientas outpatientas outpatientas outpatient
tsh0.4-4.5as outpatientas outpatientas outpatient0.1-2.5
alt7-56as outpatientas outpatientas outpatientas outpatient
inr0.8-1.1 (crit >5)as outpatientas outpatientas outpatientas outpatient
hgb13.2-16.6 (crit <7, >20)as outpatientas outpatient6 months-5 y: 11-14 (crit <7, >20); 6-12 y: 11.5-15.5 (crit <7, >20); 13-17 y: 12-16 (crit <7, >20)11-15 (crit <7, >20)
wbc3.4-9.6 (crit <1, >30)as outpatientas outpatient1-5 y: 5.5-15.5 (crit <1, >30); 6-17 y: 4.5-13.5 (crit <1, >30)as outpatient
anc≥1.5 (crit <0.5)as outpatientas outpatientas outpatientas outpatient
plt135-317 (crit <20, >1000)as outpatientas outpatientas outpatientas outpatient
bnp≤125as outpatientas outpatientas outpatientas outpatient
trop≤34as outpatientas outpatientas outpatientas outpatient
lactate0.5-2.2 (crit >4)as outpatientas outpatientas outpatientas outpatient
vanc10-20 (crit >25)as outpatientas outpatientas outpatientas outpatient
crcl≥60 (crit <15)as outpatientas outpatientas outpatientas outpatient
phq9≤9 (crit >19)as outpatientas outpatientas outpatientas outpatient
iop10-21 (crit >29)as outpatientas outpatientas outpatientas outpatient
dbhl≤25 (crit >90)as outpatientas outpatientas outpatientas outpatient
uoRate≥0.5as outpatientas outpatientas outpatientas outpatient
fhr110-160 (crit <100, >180)as outpatientas outpatientas outpatientas outpatient
contractions0-5 (crit >6)as outpatientas outpatientas outpatientas outpatient
oxytocin≤20 (crit >30)as outpatientas outpatientas outpatientas outpatient
rom≤18 (crit >24)as outpatientas outpatientas outpatientas outpatient
ebl≤500 (crit >1000)as outpatientas outpatientas outpatientas outpatient

Measures for labor and delivery (fhr, contractions, oxytocin, rom, ebl) and some unit protocols (uoRate) are protocol thresholds rather than lab reference ranges. They sit in the registry so every screen flags them the same way. Some screens also apply their own protocol rules that are not reference ranges: the ESI danger-zone vitals in TriageForm (HR above 100, RR above 20, SpO2 below 92%), the regimen hold limits in OncologyRegimen, and the severe-range blood pressure alert text in PrenatalFlowsheet. Those are not changed by the range context.

In this package​

CareOS.fmt, CareOS.RangeContext.Provider and CareOS.setRangeContext above are the named exports fmt, RangeContextProvider and setRangeContext (plus useRangeContext and withRangeContext for your own components). See Foundations, Clinical values.

Props​

PropTypeDefaultDescription
value *number | null—The measured number, unrounded: fmt rounds it to the measure's precision; required
measurestringnoneKey of fmt.MEASURES ('potassium', 'temp', 'bpSys'...) or a range-registry key/alias
loincstringthe measure's LOINCLOINC code; finds the measure when `measure` is absent
unitstringthe measure's unit. A different unit drops the sample range (it is in the measure's unit) unless a lab range is passedUCUM unit code of `value`
precisionnumberthe measure's precision, else 0Decimals
refLownumberfrom the registryLab reference low (FHIR Observation.referenceRange); with `refHigh` it replaces the registry range in every context
refHighnumberfrom the registryLab reference high
critLownumberthe registry's critical low for the contextLab critical low
critHighnumberthe registry's critical high for the contextLab critical high
flagFlagCodecomputedLab flag; overrides the computed one ('A'/'AA' for results with no direction)
trendClinicalValueTrendnoneTrend arrow, read as rising / falling / unchanged
deltastringnoneChange text shown after the arrow ('+0.6')
timestampstringnoneISO time of the result, shown in the tooltip and meta line
timeZonestringthe browser zoneIANA zone for the timestamp
sourcestringnonePerforming lab or device
statusClinicalValueStatus'final'Result status; 'entered-in-error' strikes the value through, greys it and never flags it
sizeClinicalValueSize'md''sm' | 'md' | 'lg'
labelstringthe measure labelLabel override
showMetabooleanfalseSecond line with range, time and source
showLabelbooleanfalseShows the measure name before the value
showNormalbooleanfalseShows the N flag for normal values
tooltipbooleantrueRange tooltip on hover and focus
rangeContextRangeContextIdthe nearest RangeContextProvider, else the global setRangeContext, else `defaultRangeContext`, else 'outpatient'Which registry range applies: 'outpatient' | 'inpatient' | 'ed' | 'pediatric' | 'pregnancy'. The lab range (refLow/refHigh) still wins
defaultRangeContextRangeContextIdcontext, used only when no prop, provider or global context applies; default noneThe containing set's
ageYearsnumbernone (oldest band)Age in years; picks the pediatric band in the 'pediatric' context
flagVariantAbnormalFlagVariant'compact'Flag variant for non-critical flags (critical flags always show the word)
displaystringnonePreformatted text shown instead of the formatted value (e.g. '>1000')

Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, plus className and event handlers on the root element.

Angular, Vue and HTML​

Register the elements once (Angular guide), then use <co-clinical-value>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.

Angular template
<co-clinical-value value="…" measure="…" [defaultValue]="defaultValue"></co-clinical-value>
KindNameDescription
attributevalueThe measured number, unrounded: fmt rounds it to the measure's precision; required
attributemeasureKey of fmt.MEASURES ('potassium', 'temp', 'bpSys'...) or a range-registry key/alias; default none
attributeloincLOINC code; finds the measure when `measure` is absent; default the measure's LOINC
attributeunitUCUM unit code of `value`; default the measure's unit. A different unit drops the sample range (it is in the measure's unit) unless a lab range is passed
attributeprecisionDecimals; default the measure's precision, else 0
attributeref-low / refLowLab reference low (FHIR Observation.referenceRange); with `refHigh` it replaces the registry range in every context; default from the registry
attributeref-high / refHighLab reference high; default from the registry
attributecrit-low / critLowLab critical low; default the registry's critical low for the context
attributecrit-high / critHighLab critical high; default the registry's critical high for the context
attributeflagLab flag; overrides the computed one ('A'/'AA' for results with no direction); default computed
attributetrendTrend arrow, read as rising / falling / unchanged; default none
attributedeltaChange text shown after the arrow ('+0.6'); default none
attributetimestampISO time of the result, shown in the tooltip and meta line; default none
attributetime-zone / timeZoneIANA zone for the timestamp; default the browser zone
attributesourcePerforming lab or device; default none
attributestatusResult status; 'entered-in-error' strikes the value through, greys it and never flags it; default 'final'
attributesize'sm' | 'md' | 'lg'; default 'md'
attributelabelLabel override; default the measure label
attributeshow-meta / showMetaSecond line with range, time and source; default false
attributeshow-label / showLabelShows the measure name before the value; default false
attributeshow-normal / showNormalShows the N flag for normal values; default false
attributetooltipRange tooltip on hover and focus; default true
attributerange-context / rangeContextWhich registry range applies: 'outpatient' | 'inpatient' | 'ed' | 'pediatric' | 'pregnancy'. The lab range (refLow/refHigh) still wins; default the nearest RangeContextProvider, else the global setRangeContext, else `defaultRangeContext`, else 'outpatient'
attributedefault-range-context / defaultRangeContextThe containing set's default context, used only when no prop, provider or global context applies; default none
attributeage-years / ageYearsAge in years; picks the pediatric band in the 'pediatric' context; default none (oldest band)
attributeflag-variant / flagVariantFlag variant for non-critical flags (critical flags always show the word); default 'compact'
attributedisplayPreformatted text shown instead of the formatted value (e.g. '>1000'); default none
attributedefault-checked / defaultChecked
property / JSON attributedefault-value / defaultValue
attributeauto-focus / autoFocus