Value Readout
value-readoutViewersA big honest number: tabular, unitted, and a dash when there is nothing.
$ pnpm dlx shadcn@latest add @pluginui/core-value-readoutInstall
Copies the source into your project. Anything it depends on comes with it. Run this in your React project with shadcn initialized; no registry configuration is needed.
Pulls in
Install using the registry URL
$ pnpm dlx shadcn@latest add https://pluginui.com/r/core-value-readout.jsonUsage
Connect the documented props to your application or host.
import { ValueReadout } from "@/components/ui/value-readout"
// A live value, coloured by whether it is past the budget.
<ValueReadout
label="Reduction"
value={reduction.toFixed(1)}
unit="dB"
accent={reduction > budget ? "var(--uikit-accent-2)" : undefined}
size="lg"
/>
// No source: an em dash and a note, never a fabricated 0.0.
<ValueReadout label="Reduction" value={null} unit="dB" note="No tap from this host" />About Value Readout
The REDUCTION / -14.0 dB element used by every meter-bearing face, made once. It enforces three rules. The value uses monospace with tabular figures, so its digits do not reflow while a live reading changes. The unit is a separate muted element beside the value, letting the eye read magnitude first and allowing a face to hide the unit without shifting the number's typography. A missing value prints an em dash, never zero. Showing 0.0 dB without a source would claim a measurement the meter never received; hosted face feeds follow the same “absent is not zero” rule. A real zero still prints as zero, so a measured 0.0 cannot be confused with no reading. The note line carries qualifiers such as “predicted”, “reference pattern” or “no tap from this host” in secondary text, where they do not compete with the value. An accent recolours only the value, never a placeholder, so an em dash is not lit like a live reading.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| label | ReactNode | — | Caption above the value. Short, uppercase by convention. |
| value | ReactNode | — | The value. A string prints verbatim (the host owns the rounding policy, so the readout imposes none); null, undefined, a non-finite number or an empty string print an em dash instead of a fabricated zero. A real 0 still prints as 0. |
| unit | ReactNode | — | Unit beside the value, smaller and muted so the magnitude reads first. |
| note | ReactNode | — | Secondary line below the value. Use it for a qualifier that keeps the number honest, not for extra precision. |
| accent | string | — | Recolour the value and unit to show a budget overrun or warning state. This never applies to a placeholder. |
| size | "sm" | "md" | "lg" | "md" | Type scale. A table of three deliberate sizes rather than a continuum, so the value/unit ratio stays right at each. |
| align | "start" | "center" | "end" | "start" | Alignment of the whole block. |
Interaction
- Drag with pointer capture, so the gesture keeps tracking past the edge of the control.
- Shift while dragging for a fine pass; release it mid-gesture and coarse tracking resumes.
- Double-click resets to
defaultValue. - Arrow keys step normally, Shift+arrow steps finely, PageUp/PageDown jump by ten, Home/End go to the extremes.
- Proper
sliderandswitchroles with livearia-valuetext, so a screen reader announces the formatted value rather than the raw number. - The scroll wheel adjusts the value while the pointer is over the control; stepped ranges move at least one declared step per notch by default.