GoalRing

Preview

Installation

pnpm dlx shadcn@latest add @opsinjs/goal-ring

Usage

import { GoalRing } from "@/components/ui/goal-ring"

<GoalRing
  label="Steps today"
  value={6200}
  goal={8000}
  unit="steps"
  category="activity"
/>

When to use it

Clinical meaning

Asserts. One thing: this value is this far towards a goal the product set. The fraction is arithmetic over the two values, and the readout prints both in the reader's locale, unit after. The fill is drawn where the reading sits, and nothing sweeps on first paint.

Never read as. A diagnosis, a verdict on the reader, or a target opsinjs chose. A full ring means the product's goal was met, never that the reader is well, and an open ring never means something is wrong. It rewards no streak, and "normal" and "abnormal" appear in no state it draws.

Colour axis. Category only. The fill takes the identity tint of what the ring counts, the track stays neutral, and no element carries data-status.

Thresholds. None. The product owns the goal, the label and the unit; GoalRing ships no default goal and no clinical vocabulary.

Anatomy

Examples

Progress towards a goal

A synthetic step count part-way towards a goal the product set. category="activity" tints the fill and the sentence beneath names the progress without praise.

No reading yet

value={null} draws an empty ring and words that say nothing has been measured, never a zero.

Content guidelines

Write the label as the reader's own name for what the ring counts: "Steps today", not a metric code. Keep the unit in their words too. Never phrase the copy as a challenge, and never put a streak counter or celebration beside it. When the goal is met the ring says so and stops.

Accessibility

Checked by pnpm run check:a11y on every commit.

• No element carries both axes: the fill carries data-category alone and nothing stamps data-status.
• No raw colour literal and no ramp step. The track is the neutral border role and the fill a category -accent role.
• No type size in pixels: label, readout and sentence are the subheadline, title2 and footnote steps.

Audited against WCAG 2.2 AA. A source pass and a rendered pass both ran and found nothing to change in the source. This is an author audit, not an independent review, and clinical review is still pending. The graphic is role="img" with an accessible name that speaks the label, the value against the goal and the progress sentence, all repeated in the visible words beside it. Nothing takes focus or animates on first paint, so there is no keyboard contract. Three states stay three: a finite value draws a fill, null says "no reading yet", a broken value says "not available". Under forced colours the track maps to CanvasText and the fill to Highlight.

Residual. No contrast pair is measured, so the page prints the contrast pairs as unmeasured rather than as a pass. The arc and track repeat every fact in the visible text and the accessible name, so under 1.4.11 they are not graphical objects required to understand the content. A read-only display carries no live region, so a screen reader is not told when the value changes over time; the product owns whether to wrap the ring in a live region.

Data attributes

API reference

value is number | null: null is no reading and is never drawn as zero, and a non-finite value is announced as "not available". A goal of zero or less draws an empty ring and raises a development warning. category outside the six known names is refused with a development warning and the fill falls back to neutral.

Related

• ScoreDial is a composite number against a scale with named bands.
• MetricTile is one reading on its own, with no goal to measure it against.
• RangeBar is a reading against a reference range, where the band it lands in is the meaning.