Components
ReadingInput
A field for typing in a measurement, with the unit shown and switchable beside the number, and room for an advisory the product wrote.
Usage
pnpm dlx shadcn@latest add @opsinjs/reading-input
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 { ReadingInput } from "@/components/ui/reading-input"<ReadingInput
label="Example measurement"
unit={unit}
units={["kg", "lb", "st"]}
precision={1}
value={reading}
onChange={(next) => {
setReading(next.value)
setUnit(next.unit)
}}
/>Examples
reading-input · base base · style base-lyraOpen under the product themeTwo numbers that are one measurement
segments turns the field into a <fieldset> with a <legend>, one box per part.
reading-input-a-compound-reading · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { ReadingInput, type ReadingSegment } from "@/components/ui/reading-input"
export default function ReadingInputACompoundReading() {
const [parts, setParts] = useState<ReadingSegment[]>([
{ label: "First part", value: 10 },
{ label: "Second part", value: 20 },
])
return (
<div className="w-full max-w-md">
<ReadingInput
hint="Both parts, in whole numbers"
label="Example measurement"
name="example-measurement"
onChange={(next) => setParts(next.segments)}
segments={parts}
unit="mmHg"
/>
</div>
)
}Switching the unit, and the sentence that follows it
precision sets the decimal places a conversion rounds to.
reading-input-switching-the-unit · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { ReadingInput } from "@/components/ui/reading-input"
export default function ReadingInputSwitchingTheUnit() {
const [reading, setReading] = useState<number | null>(10)
const [unit, setUnit] = useState("kg")
return (
<div className="w-full max-w-md">
<ReadingInput
hint="To one decimal place"
label="Example measurement"
name="example-measurement"
onChange={(next) => {
setReading(next.value)
setUnit(next.unit)
}}
precision={1}
unit={unit}
units={["kg", "lb", "st"]}
value={reading}
/>
</div>
)
}A sentence the product wrote
warning shows the product's sentence without comparing anything.
reading-input-a-warning-the-product-owns · base base · style base-lyraOpen under the product theme"use client"
import { useState } from "react"
import { ReadingInput } from "@/components/ui/reading-input"
export default function ReadingInputAWarningTheProductOwns() {
const [reading, setReading] = useState<number | null>(1400)
return (
<div className="w-full max-w-md">
<ReadingInput
hint="To one decimal place"
label="Example measurement"
name="example-measurement"
onChange={(next) => setReading(next.value)}
unit="kg"
value={reading}
warning={
reading === null
? undefined
: "That is a long way above most readings. It is worth checking the number before you save it."
}
/>
</div>
)
}When to use it
Use it when
- Anywhere a person types a measurement of themselves: weight, blood pressure, glucose, temperature.
- Entry where the unit is part of the value.
- Entry where the product flags an unlikely number without stopping anybody.
Do not use it when
- A quantity, a count or a code, not a measurement of a person.Use
number-fieldinstead. - The value is best chosen from a small set rather than typed.Use
segmented-controlinstead. - The reader estimates the value, such as a pain score, not measures it.Use
scale-inputinstead. - You are displaying a reading, not collecting one.Use
valueinstead. - Several related measurements captured in one interaction.Use
log-sheetinstead.
Clinical meaning
Asserts. That the reader typed this number, in this unit, as a measurement of themselves. It is always self-reported.
Never read as. A validated measurement, a device reading or an assessed value.
Colour axis. Neither; the advisory is ordinary foreground.
Thresholds. None. The component holds no bound. The product
supplies the finished warning, which never sets aria-invalid, moves focus or blocks
submission. Staleness belongs to
Trends and uncertainty.
Unit switches. Only definitional conversions from tokens/units.json: kg, lb, st,
°C and °F. mmol/L to mg/dL is refused, because the factor is the substance's molar mass,
so that switch clears the entry and says so. See
Numbers and units.
Accessibility
From the source. Field renders a real <label for>, and a compound reading is a
<fieldset> of one Field per part. The unit's spoken form joins the box's description,
each option carries its plural on aria-label, and the box is type="text" with
inputMode defaulting to decimal. The advisory and the effect line are descriptions,
with no aria-invalid and no focus move. The audit made autoComplete a prop reaching
Field.Control, defaulting to "off", because a self-reported reading has no WCAG
autofill token and the component invents none (1.3.5).
Residual items.
- The effect line reporting a switch sits in no live region, so a product must wire
effectTextto a polite announcer. Without that, a non-sighted reader hears the new unit but not that the number changed. - No hit area is measured.
- The boundary inherits
--borderwithout a gated pair.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves to the box, then the unit switch | Three stops on a compound reading: two boxes and the switch. |
| Shift+Tab | Moves backwards through the same stops | Reverse order matches the visual order. |
| Any digit, . or , | Types into the focused box | Nothing is rejected, clamped or reformatted while typing. |
| Up / Down | Changes the unit when the switch has focus | Native select. The entry converts or clears, and the line says which. |
| Enter | Whatever the surrounding form does | Nothing is swallowed. Set enterKeyHint to name the return key's action. |
| Escape | Nothing here | No overlay to dismiss, no entry to revert. |
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 ReadingInputProps in registry/bases/base/reading-input.tsx.
unit is required and value is in it. Without precision a conversion is not rounded.
There is no error prop: an error belongs to Field.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root, the control row, every segment and the unit, always. | reading-input, reading-input-control, reading-input-segment, reading-input-unit |
| data-slot | Legend and hint on a compound reading, warning when supplied, effect after a switch. | reading-input-legend, reading-input-hint, reading-input-warning, reading-input-effect |
| data-opsinjs-value | On every ReadingInput.Segment, always | The number in that box, read off the box not the prop |
| data-status, data-category | Never, at any value of any prop | Never set |