---
title: "Value"
description: "A number and its unit, formatted one way everywhere. It is rounded honestly, spoken correctly, and never shown to more precision than the measurement has."
url: "https://opsinjs.pensievelabs.org/docs/components/value"
source: "https://opsinjs.pensievelabs.org/docs/components/value.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-formatting"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["number", "unit", "format", "formatted number", "format a number", "numeric display", "figure"]
governedBy: ["numbers", "health/index", "trends", "consent-and-privacy", "reference-ranges", "safety-review"]
usedIn: ["daily-logging", "forms", "result-disclosure", "onboarding-and-first-run", "sharing-with-a-clinician", "trend-review"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="value"
  status="shipped"
  questions="[
  &#x22;Whether a per-language spoken unit form belongs in tokens/units.json, in the product, or in neither, given that only an English reader hears words today.&#x22;,
  &#x22;Whether a hero value should move from title1 up to largeTitle, an answer that changes every hero number in MetricTile, ResultCard, ScoreDial and RangeBar at once.&#x22;,
  &#x22;Whether the muted absence at the display size clears contrast, and how the value behaves at 200% text, since neither has been looked at in either theme.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="value" unbuilt="false" importPath="@/components/ui/value" />

```tsx
import { Value } from "@/components/ui/value"
```

```tsx
<Value value={1000.2} unit="kg" precision={1} />
```

## Examples [#examples]

<ComponentPreview name="value" />

### Zero is a reading. Absence is not. [#zero-is-a-reading-absence-is-not]

Three rows share a unit and a precision and differ only in the reading: a
number, a `null`, and a number that arrived broken. Rule 12 of
[Numbers and units](../health/numbers.mdx) keeps them apart.

<ComponentPreview name="value-zero-is-not-absence" kind="example" align="start" />

### One precision makes a column comparable [#one-precision-makes-a-column-comparable]

Four readings of one metric at one `precision`, aligned by the layout and by
tabular figures.

<ComponentPreview name="value-aligned-in-a-column" kind="example" align="start" />

### What a screen reader is actually given [#what-a-screen-reader-is-actually-given]

One magnitude with six units, and beside each the phrase that reaches speech.

<ComponentPreview name="value-spoken-units" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;Any number displayed to a reader that has a unit, a precision, or both.&#x22;,
  &#x22;Inside other components: the reading in a MetricTile, the number beside a RangeBar tick, the score in a ScoreDial.&#x22;,
  &#x22;Anywhere the same measurement appears on more than one screen and must look identical on all of them.&#x22;,
]"
  avoid="[
  { case: &#x22;The number needs its reference range shown alongside it to mean anything.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;The number is a point in time rather than a quantity.&#x22;, instead: &#x22;relative-time&#x22; },
  { case: &#x22;You are collecting the number rather than displaying it.&#x22;, instead: &#x22;reading-input&#x22; },
  { case: &#x22;The number needs a label, a timestamp and a surface of its own.&#x22;, instead: &#x22;metric-tile&#x22; },
  { case: &#x22;The number is a proportion or a risk that needs a denominator and a natural-frequency framing.&#x22;, instead: &#x22;callout&#x22; },
]"
/>

## Clinical meaning [#clinical-meaning]

**Asserts.** That this quantity has this magnitude in this unit, to this
precision. `1000.2` and `1000.20` claim different things.

**Never read as.** A judgement. Value carries no status and no band; a bare
number means nothing without the context its surface supplies.

**Colour axis.** Neither. A reading inherits the text colour of its context. An
absence at `display` takes the muted theme role.

**Thresholds.** None here, and none in `tokens/units.json`, which holds no
reference range, no plausibility bound and no default precision. Precision
belongs to the metric, so `precision` is required. See
[Numbers and units](../health/numbers.mdx) and
[Reference ranges](../health/reference-ranges.mdx).

**Masking.** [Consent and privacy](../health/consent-and-privacy.mdx) lists this
among the components that implement a fixed-width mask. Value has no `masked`
prop and reserves no width, so masking a reading today moves the layout.

<SafetyCallout severity="attention" evidence="opinion" title="The unit table says what a number is measured in. It never says what a number should be.">
  `mmol/L` to `mg/dL` is refused, because the factor is a property of the analyte
  rather than of either unit. `convertUnit` returns nothing rather than a
  substituted default. See [Numbers and units](../health/numbers.mdx).
</SafetyCallout>

## Accessibility [#accessibility]

The unit symbol is `aria-hidden` only when a spoken form exists and the words
follow it, so an English reader hears *1000.2 kilograms* as one phrase. Absence
is spoken in words, never drawn at hero weight, and carries no decorative glyph.
The component imposes no truncation, no fixed height and no `whitespace-nowrap`.
Axe, target-size, focus-visible and 320px reflow checks came back empty, and the
audit changed nothing in source.

**Residual items.**

* A Value must never be the sole accessible name of a tappable control, because
  the visible symbol and the spoken words share no substring. The control owes
  its own name carrying the symbol (WCAG 2.2 SC 2.5.3).
* The only path to a clipped reading is a caller passing a truncating class
  through `className`, which `twMerge` lets win, so truncation is a caller
  responsibility documented on `ValueProps.className`.
* The spoken span uses `select-none` to keep the words off the clipboard while
  leaving them in the accessibility tree, untested by a copy test.

<KeyboardTable
  name="value"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the value&#x22;,
    notes: &#x22;Not focusable, by contract. Thirty readings would otherwise be thirty tab stops doing nothing.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the value&#x22;,
    notes: &#x22;Same in reverse. A tappable row owes its own name and its own 44 by 44.&#x22;,
  },
]"
/>

<ContrastReport component="value" />

## Props interface [#props-interface]

<PropsTable name="ValueProps" />

`precision` is required and nothing is defaulted in its place. `unit={null}`
declares a dimensionless number. Omitting `unit` raises OPSIN-0003 instead.
Under server rendering, pass `locale` explicitly, or the server's own ICU
default formats the first paint and hydration reformats it.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="value"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On the root and every inner part, when that part renders&#x22;,
    value: &#x22;value, value-number, value-unit, value-spoken, value-absence&#x22;,
  },
  {
    attribute: &#x22;data-opsinjs-value&#x22;,
    condition: &#x22;On the root, always&#x22;,
    value: &#x22;The unrounded reading, or an empty string when there is no reading&#x22;,
  },
]"
/>
