Components
Value
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.
Usage
pnpm dlx shadcn@latest add @opsinjs/value
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { Value } from "@/components/ui/value"<Value value={1000.2} unit="kg" precision={1} />Examples
value · base base · style base-lyraOpen under the product themeZero 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 keeps them apart.
value-zero-is-not-absence · base base · style base-lyraOpen under the product themeimport { Value } from "@/components/ui/value"
const ROWS = [
{
label: "First example measurement",
value: 0 as number | null,
note: "A measurement was taken. It came to zero.",
},
{
label: "Second example measurement",
value: null as number | null,
note: "No measurement has been taken. Nothing is being claimed about it.",
},
{
label: "Third example measurement",
value: Number.NaN,
note: "A measurement exists and did not survive the trip. This is a failure rather than an absence, and it says so in different words.",
},
]
export default function ValueZeroIsNotAbsence() {
return (
<dl className="m-0 flex w-full max-w-md flex-col gap-opsin-4 p-0 text-opsin-body">
{ROWS.map((row) => (
/* Label and reading share a line while there is room, and stack when
there is not. A fixed two-column grid could not do this: a `1fr`
track never shrinks below the widest word of the label, so at 200%
text on a narrow phone the label column plus the reading column ran
past the viewport and pushed the whole page sideways. A wrapping flex
row lets the reading fall onto its own line instead, held to the
right by `ml-auto` so a column of numbers still lines up. The join
between a number and its unit is left alone, because that join is a
no-break space inside Value and is never the thing that wraps. */
<div
key={row.label}
className="flex flex-wrap items-baseline gap-x-opsin-4 gap-y-opsin-1 border-b border-border pb-opsin-2"
>
<dt className="m-0 min-w-0 flex-auto">{row.label}</dt>
<dd className="m-0 ml-auto text-right">
<Value value={row.value} unit="steps" precision={0} />
</dd>
{/* The same term, defined a second time in words. It takes the full
width of its own line so the sentence stays on the reading measure
rather than being squeezed into the width of the number beside
it. */}
<dd className="basis-full m-0 text-opsin-footnote text-muted-foreground">
{row.note}
</dd>
</div>
))}
</dl>
)
}One precision makes a column comparable
Four readings of one metric at one precision, aligned by the layout and by
tabular figures.
value-aligned-in-a-column · base base · style base-lyraOpen under the product themeimport { Value } from "@/components/ui/value"
/* THE DIGITS ARE THE POINT AND THE MAGNITUDES ARE NOT. An alignment demo needs
numbers of different widths or it demonstrates nothing, so this one has three
digits, four, four and five. Every one of them is nevertheless above eight
hundred kilograms, which is not a person and not a series anybody could read
as their own. An earlier draft ran from single figures upward, and its first
two rows were plausible weights for a small child. This file ships as
registry source under `shadcn add` and is captured as a preview image, which
is the case ADR 0012 is written about: the number is the part a reader acts
on, and it travels further than the caption that explains it. */
const READINGS = [
{ when: "Fourth reading", value: 800 },
{ when: "Third reading", value: 1250.5 },
{ when: "Second reading", value: 3000 },
{ when: "First reading", value: 10000.25 },
]
export default function ValueAlignedInAColumn() {
return (
/* The scroll container is the table's own rather than the page's. A table
cannot be laid out narrower than its min-content width, and every cell in
the right column is an unbreakable run by construction. The no-break
space inside Value is what holds a number to its unit. At 200% text those
runs roughly double and the table outgrows `max-w-md`; without this
wrapper the document scrolls sideways, which is the failure
`accessibility/text-resizing-and-zoom` names and the one the value page
claims this design avoids. */
<div className="w-full overflow-x-auto">
<table className="w-full max-w-md border-collapse text-opsin-body">
<caption className="mb-opsin-2 text-left text-opsin-footnote text-muted-foreground">
Example measurement, in kilograms, to two decimal places. The figures
are invented and are not anybody’s readings.
</caption>
<tbody>
{READINGS.map((reading) => (
<tr key={reading.when} className="border-b border-border">
<th
scope="row"
className="py-opsin-2 text-left font-normal text-muted-foreground"
>
{reading.when}
</th>
<td className="py-opsin-2 text-right">
<Value value={reading.value} unit="kg" precision={2} />
</td>
</tr>
))}
</tbody>
</table>
</div>
)
}What a screen reader is actually given
One magnitude with six units, and beside each the phrase that reaches speech.
value-spoken-units · base base · style base-lyraOpen under the product themeimport { spokenUnit } from "@/lib/opsinjs"
import { Value } from "@/components/ui/value"
/* Every symbol here is in the unit table. A symbol that is NOT in it renders as
written and is left in the accessibility tree unchanged rather than handed a
pronunciation somebody guessed. The result is awkward to listen to, and it is
true. */
const SYMBOLS = ["kg", "mmol/L", "mmHg", "bpm", "°C", "%"]
const SAMPLE = 888
export default function ValueSpokenUnits() {
return (
/* The scroll container is the table's own rather than the page's. A table
cannot be laid out narrower than its min-content width, and every cell in
the left column is an unbreakable run by construction. The no-break space
inside Value is what holds a number to its unit. At 200% text those runs
roughly double and the table outgrows `max-w-lg`; without this wrapper the
document scrolls sideways, which is the failure
`accessibility/text-resizing-and-zoom` names and the one the value page
claims this design avoids. */
<div className="w-full overflow-x-auto">
<table className="w-full max-w-lg border-collapse text-opsin-body">
<thead>
<tr className="border-b border-border">
<th
scope="col"
className="py-opsin-2 text-left font-normal text-muted-foreground"
>
What is on the screen
</th>
<th
scope="col"
className="py-opsin-2 text-left font-normal text-muted-foreground"
>
What a screen reader is given
</th>
</tr>
</thead>
<tbody>
{SYMBOLS.map((symbol) => (
<tr key={symbol} className="border-b border-border">
<td className="py-opsin-2">
<Value value={SAMPLE} unit={symbol} precision={0} />
</td>
<td className="py-opsin-2 text-muted-foreground">
{SAMPLE} {spokenUnit(symbol, SAMPLE)}
</td>
</tr>
))}
</tbody>
</table>
</div>
)
}When to use it
Use it when
- Any number displayed to a reader that has a unit, a precision, or both.
- Inside other components: the reading in a MetricTile, the number beside a RangeBar tick, the score in a ScoreDial.
- Anywhere the same measurement appears on more than one screen and must look identical on all of them.
Do not use it when
- The number needs its reference range shown alongside it to mean anything.Use
range-barinstead. - The number is a point in time rather than a quantity.Use
relative-timeinstead. - You are collecting the number rather than displaying it.Use
reading-inputinstead. - The number needs a label, a timestamp and a surface of its own.Use
metric-tileinstead. - The number is a proportion or a risk that needs a denominator and a natural-frequency framing.Use
calloutinstead.
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 and
Reference ranges.
Masking. Consent and privacy 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.
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, whichtwMergelets win, so truncation is a caller responsibility documented onValueProps.className. - The spoken span uses
select-noneto keep the words off the clipboard while leaving them in the accessibility tree, untested by a copy test.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the value | Not focusable, by contract. Thirty readings would otherwise be thirty tab stops doing nothing. |
| Shift+Tab | Skips the value | Same in reverse. A tappable row owes its own name and its own 44 by 44. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from ValueProps in registry/bases/base/value.tsx.
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
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every inner part, when that part renders | value, value-number, value-unit, value-spoken, value-absence |
| data-opsinjs-value | On the root, always | The unrounded reading, or an empty string when there is no reading |