---
title: "ScoreDial"
description: "A single composite score shown on a dial with its band named in words, alongside an honest statement of what went into the number."
url: "https://opsinjs.pensievelabs.org/docs/components/score-dial"
source: "https://opsinjs.pensievelabs.org/docs/components/score-dial.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-data-display"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["gauge", "dial", "ring", "score", "index", "bmi"]
governedBy: ["reference-ranges", "numbers", "two-colour-axes", "alerts"]
implemented: true
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> `<StubNotice>` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.

<StubNotice
  name="score-dial"
  status="shipped"
  questions="[
  &#x22;No provenance field exists, and nothing checks that the derivation names which inputs were device estimates and which the reader typed.&#x22;,
  &#x22;The indicator against its tinted band fails the non-text contrast floor in both themes, and whether that arc may ship is open.&#x22;,
  &#x22;The component mounts no live region, so what a screen reader hears when a score changes is unspecified.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="score-dial" unbuilt="false" importPath="@/components/ui/score-dial" dependencies="[&#x22;lucide-react&#x22;]" registryDependencies="[&#x22;value&#x22;, &#x22;status-pill&#x22;]" />

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

```tsx
<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"
/>
```

## Examples [#examples]

<ComponentPreview name="score-dial" />

### opsinjs ships no bands [#opsinjs-ships-no-bands]

The dial is drawn as an instrument: a lit bezel, a ruled face, the scale's two ends and a needle on a hub. With an empty `bands`, it draws the scale, places the needle and names no band.

<ComponentPreview name="score-dial-no-bands-supplied" kind="example" align="start" />

### A score built from less than usual [#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.

<ComponentPreview name="score-dial-partial-data" kind="example" align="start" />

### Zero is a score; absence is not [#zero-is-a-score-absence-is-not]

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

<ComponentPreview name="score-dial-zero-is-not-absence" kind="example" align="start" />

## When to use it [#when-to-use-it]

<WhenToUse
  use="[
  &#x22;A questionnaire total, a readiness index, or any score you calculated, meaningful only against its own bands.&#x22;,
  &#x22;A bounded score whose scale the reader has no intuition for, where position carries more than digits.&#x22;,
  &#x22;A score whose derivation you can state in one sentence, on the same screen.&#x22;,
]"
  avoid="[
  { case: &#x22;The number is a measurement rather than a calculation, with a published reference range.&#x22;, instead: &#x22;range-bar&#x22; },
  { case: &#x22;You cannot say what went into the score, or it is a risk or probability, which a dial must never draw as an angle.&#x22;, instead: &#x22;value&#x22; },
  { case: &#x22;The score is only meaningful as a trajectory, so one number says nothing alone.&#x22;, instead: &#x22;trend-sparkline&#x22; },
  { case: &#x22;You are showing completion of something the person is doing, such as steps against a goal.&#x22;, instead: &#x22;progress&#x22; },
  { case: &#x22;The score crossed a threshold that needs action now. The dial refuses attention and urgent.&#x22;, instead: &#x22;care-card&#x22; },
]"
/>

## Clinical meaning [#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.
[Numbers and units](../health/numbers.mdx) keeps probabilities off it, and 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`, and other bands stay neutral. Category tints the label
alone, so [two colour axes](../health/two-colour-axes.mdx) never meet.

**Thresholds.** The product owns every band and cut-off, and opsinjs ships none.
`ScoreBand.source` is required, as [Reference ranges](../health/reference-ranges.mdx)
demands. `status` is an input, never derived, and `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.

<SafetyCallout severity="attention" evidence="opinion">
  When only part of the input data was available, `coverage` must say so. Name what was
  counted in your derivation; it will not guess a noun.
</SafetyCallout>

## Accessibility [#accessibility]

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, a glyph and `data-status`, never colour alone,
and the band name, scale, source and derivation are visible text no prop removes. One
stacked column never truncates at 200% text, nothing animates, and nothing is
interactive, so keyboard and pointer criteria pass vacuously. It renders clean for axe,
target size and 320px reflow, and the audit changed nothing.

**Residual items.**

* The static, read-only dial mounts no live region, so nothing announces a score change.
  Adding one is a recommended enhancement, not a fix.
* The tinted band strokes fall below the non-text floor in light, and stay because the
  band name, the StatusPill word and glyph, the indicator and `data-status` say the same
  thing.
* The arc stroke against its card is not in the measured set, and the source records the
  pair without a number.

<KeyboardTable
  name="score-dial"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the dial&#x22;,
    notes: &#x22;A picture of a reading, not a control.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the dial&#x22;,
    notes: &#x22;The SVG carries focusable=\&#x22;false\&#x22;.&#x22;,
  },
]"
/>

<ContrastReport component="score-dial" />

## Props interface [#props-interface]

<PropsTable name="ScoreDialProps" />

`bands` is required with no default, and may be an empty array. 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 and units](../health/numbers.mdx) demands. A non-finite
`value` prints and speaks *not available*.

### Data attributes [#data-attributes]

<DataAttributesTable
  name="score-dial"
  rows="[
  {
    attribute: &#x22;data-slot&#x22;,
    condition: &#x22;On every part that renders&#x22;,
    value: &#x22;score-dial, score-dial-label, score-dial-track, score-dial-band, score-dial-boundary, score-dial-indicator, score-dial-reading, score-dial-score, score-dial-band-name, status-pill, score-dial-coverage, score-dial-scale, score-dial-band-source, score-dial-derivation, score-dial-calculated-line, score-dial-calculated-at&#x22;,
  },
  {
    attribute: &#x22;data-status&#x22;,
    condition: &#x22;On the band the score fell in, the indicator and the StatusPill&#x22;,
    value: &#x22;steady | watch&#x22;,
  },
  {
    attribute: &#x22;data-category&#x22;,
    condition: &#x22;On ScoreDial.Label, with a category&#x22;,
    value: &#x22;sleep | heart | activity | nutrition | mind | labs&#x22;,
  },
  {
    attribute: &#x22;data-opsinjs-value&#x22;,
    condition: &#x22;On the Value inside ScoreDial.Score&#x22;,
    value: &#x22;The unrounded number, or empty with no reading&#x22;,
  },
]"
/>
