Components
GoalRing
A ring that shows how far a reading has come towards a goal the product set, paired with a text twin that states every figure, and rewarding no streak.
Usage
pnpm dlx shadcn@latest add @opsinjs/goal-ring
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 { GoalRing } from "@/components/ui/goal-ring"<GoalRing
label="Steps today"
value={6200}
goal={8000}
unit="steps"
category="activity"
/>Examples
goal-ring · base base · style base-lyraOpen under the product themeProgress 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.
goal-ring-progress-to-a-goal · base base · style base-lyraOpen under the product themeimport { GoalRing } from "@/components/ui/goal-ring"
export default function GoalRingProgressToAGoal() {
return (
<GoalRing
label="Steps today"
value={6200}
goal={8000}
unit="steps"
category="activity"
/>
)
}No reading yet
value={null} draws an empty ring and words that say nothing has been measured,
never a zero.
goal-ring-no-reading-yet · base base · style base-lyraOpen under the product themeimport { GoalRing } from "@/components/ui/goal-ring"
export default function GoalRingNoReadingYet() {
return (
<GoalRing
label="Water today"
value={null}
goal={2000}
unit="ml"
category="nutrition"
/>
)
}When to use it
Use it when
- A single reading against a goal the product set, where the goal is the product's own rather than a clinical target.
- A daily count that resets, such as steps, active minutes or water, where the words carry the exact figures.
Do not use it when
- A composite number the product calculated, with named bands. That is a score against a scale, not progress towards a goal.Use
score-dialinstead. - One reading on its own, with its unit and when it was taken, and no goal to measure it against.Use
metric-tileinstead. - A reading against a reference range, where the meaning is which band it falls in rather than how far along a target it is.Use
range-barinstead.
Clinical meaning
Asserts. One thing: this value is this far towards a goal the product set, and the fraction is arithmetic over the two values. The readout prints both in the reader's locale, unit after, and the fill is drawn where the reading sits, with nothing sweeping 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. See
Two colour axes.
Thresholds. None. The product owns the goal, the label and the unit; GoalRing ships no default goal and no clinical vocabulary.
Accessibility
Checked by pnpm run check:a11y on every commit.
- No element carries both axes: the fill carries
data-categoryalone and nothing stampsdata-status. - No raw colour literal and no ramp step. The plate, the face and the groove are mixed from the card and foreground roles, and the fill is the category accent role.
- No type size in pixels: the label, the figure, the goal beside it and the sentence are the
subheadline,title1,bodyandfootnotesteps.
The fill had drawn in the inherited ink rather than its category, because its class named a utility the theme does not declare; it is fixed. 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", and a broken
value says "not available". Under forced colours the plate maps to Canvas, the track
to CanvasText and the fill to Highlight.
Residual items.
- 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 SC 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 one.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the whole component | A labelled image, not a control. |
| Shift+Tab | Skips the whole component | Never in the focus order. |
| Arrow keys | Nothing | Nothing to select or change. |
Contrast: 120 measured token pairs, 19 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| activity ink on activity surface | light | 88.5 | 9.61:1 | Pass |
| activity ink on activity surface | dark | -83.1 | 12.58:1 | Pass |
| activity line on activity surface | light | 67.6 | 4.42:1 | Pass |
| activity line on activity surface | dark | -69.0 | 9.93:1 | Pass |
| activity accent on activity surface | light | 44.1 | 2.34:1 | Below floor |
| activity accent on activity surface | dark | -53.3 | 7.26:1 | Pass |
| activity accent on the page | light | 46.1 | 2.41:1 | Below floor |
| activity accent on the page | dark | -54.6 | 8.22:1 | Pass |
| activity ink on the page | light | 90.5 | 9.90:1 | Pass |
| activity ink on the page | dark | -84.4 | 14.24:1 | Pass |
| activity line on the band | light | 66.1 | 4.32:1 | Pass |
| activity line on the band | dark | -67.4 | 8.60:1 | Pass |
| heart ink on heart surface | light | 89.1 | 10.51:1 | Pass |
| heart ink on heart surface | dark | -80.5 | 12.55:1 | Pass |
| heart line on heart surface | light | 70.4 | 5.05:1 | Pass |
| heart line on heart surface | dark | -64.5 | 9.46:1 | Pass |
| heart accent on heart surface | light | 60.3 | 3.64:1 | Pass |
| heart accent on heart surface | dark | -48.2 | 6.68:1 | Pass |
| heart accent on the page | light | 63.2 | 3.81:1 | Pass |
| heart accent on the page | dark | -49.5 | 7.27:1 | Pass |
| heart ink on the page | light | 92.0 | 10.97:1 | Pass |
| heart ink on the page | dark | -81.8 | 13.65:1 | Pass |
| heart line on the band | light | 69.9 | 5.01:1 | Pass |
| heart line on the band | dark | -62.8 | 7.88:1 | Pass |
| labs ink on labs surface | light | 88.8 | 9.78:1 | Pass |
| labs ink on labs surface | dark | -83.1 | 12.69:1 | Pass |
| labs line on labs surface | light | 67.9 | 4.51:1 | Pass |
| labs line on labs surface | dark | -68.4 | 9.90:1 | Pass |
| labs accent on labs surface | light | 59.3 | 3.49:1 | Pass |
| labs accent on labs surface | dark | -52.7 | 7.21:1 | Pass |
| labs accent on the page | light | 61.5 | 3.60:1 | Pass |
| labs accent on the page | dark | -53.9 | 8.07:1 | Pass |
| labs ink on the page | light | 90.9 | 10.09:1 | Pass |
| labs ink on the page | dark | -84.3 | 14.22:1 | Pass |
| labs line on the band | light | 66.5 | 4.42:1 | Pass |
| labs line on the band | dark | -66.7 | 8.49:1 | Pass |
| mind ink on mind surface | light | 89.9 | 10.36:1 | Pass |
| mind ink on mind surface | dark | -81.3 | 12.56:1 | Pass |
| mind line on mind surface | light | 70.7 | 4.94:1 | Pass |
| mind line on mind surface | dark | -65.4 | 9.54:1 | Pass |
| mind accent on mind surface | light | 60.0 | 3.55:1 | Pass |
| mind accent on mind surface | dark | -49.1 | 6.77:1 | Pass |
| mind accent on the page | light | 62.8 | 3.70:1 | Pass |
| mind accent on the page | dark | -50.0 | 7.42:1 | Pass |
| mind ink on the page | light | 92.7 | 10.80:1 | Pass |
| mind ink on the page | dark | -82.2 | 13.77:1 | Pass |
| mind line on the band | light | 70.0 | 4.89:1 | Pass |
| mind line on the band | dark | -63.4 | 8.00:1 | Pass |
| nutrition ink on nutrition surface | light | 89.3 | 10.06:1 | Pass |
| nutrition ink on nutrition surface | dark | -81.9 | 12.55:1 | Pass |
| nutrition line on nutrition surface | light | 69.7 | 4.78:1 | Pass |
| nutrition line on nutrition surface | dark | -66.7 | 9.66:1 | Pass |
| nutrition accent on nutrition surface | light | 39.2 | 2.11:1 | Below floor |
| nutrition accent on nutrition surface | dark | -50.2 | 6.88:1 | Pass |
| nutrition accent on the page | light | 41.8 | 2.19:1 | Below floor |
| nutrition accent on the page | dark | -51.3 | 7.63:1 | Pass |
| nutrition ink on the page | light | 91.9 | 10.44:1 | Pass |
| nutrition ink on the page | dark | -82.9 | 13.91:1 | Pass |
| nutrition line on the band | light | 68.8 | 4.71:1 | Pass |
| nutrition line on the band | dark | -64.8 | 8.19:1 | Pass |
| sleep ink on sleep surface | light | 89.6 | 10.19:1 | Pass |
| sleep ink on sleep surface | dark | -81.9 | 12.60:1 | Pass |
| sleep line on sleep surface | light | 70.0 | 4.80:1 | Pass |
| sleep line on sleep surface | dark | -66.4 | 9.65:1 | Pass |
| sleep accent on sleep surface | light | 64.6 | 4.05:1 | Pass |
| sleep accent on sleep surface | dark | -50.4 | 6.94:1 | Pass |
| sleep accent on the page | light | 67.3 | 4.22:1 | Pass |
| sleep accent on the page | dark | -51.4 | 7.67:1 | Pass |
| sleep ink on the page | light | 92.3 | 10.60:1 | Pass |
| sleep ink on the page | dark | -82.9 | 13.92:1 | Pass |
| sleep line on the band | light | 69.1 | 4.75:1 | Pass |
| sleep line on the band | dark | -64.5 | 8.16:1 | Pass |
| 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 |
| activity ink on the card material | light | 93.6 | 10.34:1 | Pass |
| activity ink on the card material | dark | -83.5 | 12.91:1 | Pass |
| heart ink on the card material | light | 95.1 | 11.47:1 | Pass |
| heart ink on the card material | dark | -80.9 | 12.38:1 | Pass |
| labs ink on the card material | light | 94.0 | 10.54:1 | Pass |
| labs ink on the card material | dark | -83.5 | 12.90:1 | Pass |
| mind ink on the card material | light | 95.7 | 11.28:1 | Pass |
| mind ink on the card material | dark | -81.4 | 12.49:1 | Pass |
| nutrition ink on the card material | light | 95.0 | 10.91:1 | Pass |
| nutrition ink on the card material | dark | -82.0 | 12.61:1 | Pass |
| sleep ink on the card material | light | 95.4 | 11.08:1 | Pass |
| sleep ink on the card material | dark | -82.1 | 12.62:1 | Pass |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from GoalRingProps in registry/bases/base/goal-ring.tsx.
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.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every part but the svg, always | goal-ring, goal-ring-track, goal-ring-fill, goal-ring-words, goal-ring-label, goal-ring-value, goal-ring-derivation |
| data-category | On the fill, while it is drawn with a known category | The category name, such as activity. Absent when no category is given. |