ScoreDial

Preview

Installation

pnpm dlx shadcn@latest add @opsinjs/score-dial

Usage

import { ScoreDial } from "@/components/ui/score-dial"

<ScoreDial
  label="Example composite score"
  value={14}
  min={10}
  max={20}
  precision={0}
  bands={[]}
  derivation="Example data rather than a reference range. The score and the scale here are invented."
  calculatedAt="2026-03-14T08:12:00+00:00"
/>

When to use it

Clinical meaning

Asserts. The product computed a number from stated inputs, and it fell in a named band. It asserts a calculation, never a fact about the reader's body.

Never read as. A measurement, a diagnosis, a percentage or a rank. Risk and statistics keeps probabilities off it. The scale reads on a scale of 10 to 20, never out of 20.

Colour axis. Status sits on the indicator and the band the score fell in, only when the product passed status. Other bands stay neutral. Category tints the label alone, so the two colour axes never meet.

Thresholds. The product owns every band and cut-off; opsinjs ships none. ScoreBand.source is required, as Reference ranges demands. status is an input, never derived. attention and urgent are refused.

Staleness. calculatedAt renders as a plain date, with no staleness treatment. Add a RelativeTime when an old score must read as old.

Anatomy

Examples

opsinjs ships no bands

With an empty bands, the dial draws the scale, places the number and names no band.

A score built from less than usual

coverage puts the gap on the dial's face. status="watch" is a prop on the dial, not a field on a band.

Zero is a score; absence is not

value={0} reached the bottom of its scale. value={null} never ran, so nothing is placed.

Accessibility

Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is author-run, not an independent review, and clinical review is still pending. It found nothing to change: no serious defect in the source, and a clean rendered pass over axe, target size and 320px reflow. There are no interactive elements, so keyboard and pointer criteria pass vacuously.

Argued from the source.

• The graphic is role="img" with a complete aria-label and focusable="false", never a meter, progressbar or slider, which would assert a within-range value it may not make.
• Every status tint carries a word and a glyph and stamps data-status, never colour alone.
• The band name, scale, source and derivation are visible text no prop removes, the layout is one stacked column that never truncates at 200% text, and nothing animates.

Deferred. No live region mounts, because it is static and read-only, so nothing announces a score change; adding one is a recommended enhancement, not a fix. The tinted band strokes below the non-text floor in light, left as-is because the band name, the StatusPill word and glyph, the indicator and data-status all say the same thing.

Unmeasured. The pair the arc stroke forms against its card is not in the measured set; the source records it and types no number.

Data attributes

API reference

bands is required with no default, and an empty array is legitimate. A ScoreBand carries an inclusive from, an exclusive to, a name in the reader's language and a required source. status accepts only steady | watch. precision is required, as Numbers, units and precision demands. A non-finite value prints and speaks not available.

Related

• RangeBar is a measured value against a published range, not a calculation.
• Progress is a task advancing towards a goal, not a score.
• GoalRing is the ring the reader fills by doing something.
• MetricTile is the compact readout, with no room for a derivation.
• Value is honest when the derivation cannot be stated.