Skip to content
opsinjs
Edit this page

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

Theme
Density
Text
Status
Accent theme
Accent
value · base base · style base-lyraOpen under the product theme

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 keeps them apart.

Theme
Density
Text
Status
Accent theme
Accent
value-zero-is-not-absence · base base · style base-lyraOpen under the product theme
value-zero-is-not-absence.tsx
import { 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.

Theme
Density
Text
Status
Accent theme
Accent
value-aligned-in-a-column · base base · style base-lyraOpen under the product theme
value-aligned-in-a-column.tsx
import { 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&rsquo;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.

Theme
Density
Text
Status
Accent theme
Accent
value-spoken-units · base base · style base-lyraOpen under the product theme
value-spoken-units.tsx
import { 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-bar instead.
  • The number is a point in time rather than a quantity.Use relative-time instead.
  • You are collecting the number rather than displaying it.Use reading-input instead.
  • The number needs a label, a timestamp and a surface of its own.Use metric-tile instead.
  • The number is a proportion or a risk that needs a denominator and a natural-frequency framing.Use callout instead.

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, 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.
KeyActionNotes
TabSkips the valueNot focusable, by contract. Thirty readings would otherwise be thirty tab stops doing nothing.
Shift+TabSkips the valueSame in reverse. A tappable row owes its own name and its own 44 by 44.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below 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

AttributeConditionValue
data-slotOn the root and every inner part, when that part rendersvalue, value-number, value-unit, value-spoken, value-absence
data-opsinjs-valueOn the root, alwaysThe unrounded reading, or an empty string when there is no reading