Components
SourceCitation
Where a piece of health information came from, in plain words, with an optional link to the fuller citation and an optional date it was last checked.
Usage
pnpm dlx shadcn@latest add @opsinjs/source-citation
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 { SourceCitation } from "@/components/ui/source-citation"<SourceCitation
source="Estimated by your watch from movement and heart rate."
more={{ label: "Read how this is worked out", href: "/how-it-works" }}
checkedOn="2026-03-14"
locale="en-GB"
/>Examples
source-citation · base base · style base-lyraOpen under the product themeA device estimate naming its own method
The provenance names the device and the class of the figure, so it reads as an estimate. more points at the fuller accuracy document.
source-citation-a-device-estimate · base base · style base-lyraOpen under the product themeimport { SourceCitation } from "@/components/ui/source-citation"
export default function SourceCitationADeviceEstimate() {
return (
<div className="w-full max-w-(--opsin-measure-comfortable,66ch)">
{/* A stand-in for the value the citation belongs to. It is a phrase and not
a number on purpose, so this example renders no reading a person could
read as their own. The citation is what places that value in the
device-estimated class at the moment it is read. */}
<p className="m-0 text-opsin-headline [color:var(--foreground)]">
Your example resting estimate
</p>
<div className="mt-opsin-1">
<SourceCitation
source="Estimated by your Example Watch from movement and heart rate. It works this out rather than measuring it, so read it as an estimate."
more={{
label: "Read how your Example Watch works this out",
href: "#example",
}}
checkedOn="2026-03-14"
locale="en-GB"
/>
</div>
</div>
)
}When nobody said where it came from
With no source, the citation prints an admission rather than rendering empty. Markup you wrap a source in is taken at its word.
source-citation-no-source-supplied · base base · style base-lyraOpen under the product themeimport { SourceCitation } from "@/components/ui/source-citation"
export default function SourceCitationNoSourceSupplied() {
return (
<div className="w-full max-w-(--opsin-measure-comfortable,66ch)">
{/* No `source`, which is what `{reading.source}` looks like on the day the
data layer has none. The component prints its admission and warns in
development rather than rendering an empty line. */}
<SourceCitation />
</div>
)
}When to use it
Use it when
- Beside a health value whose provenance a reader needs to weigh it: a wearable estimate, a home device reading, a typed figure.
- To attribute and link a manufacturer's accuracy document or a study you have read, rather than restating its claim as your own.
- Wherever a number's origin bounds what may be said about it, so origin travels with the number where it is read.
Do not use it when
- The message is a standing statement about the whole product, rather than the source of one value.Use
disclaimer-noteinstead. - You are saying when a reading was taken or synced, rather than where it came from.Use
relative-timeinstead. - You are explaining what a term means, rather than where a value came from.Use
terminstead. - The note is information about the content with no source to attribute.Use
calloutinstead.
Clinical meaning
Asserts. Where a health value came from, in the product's own plain words, with an optional checked date and a link to the fuller source.
Never read as. A guarantee that the source is right, current, or checked by anybody. checkedOn is the date the product recorded, and a value old enough to doubt is wrapped in RelativeTime beside it.
Colour axis. Neither: no status prop and no category prop, and a class from either axis raises a development warning. See Two colour axes.
Thresholds. None. No reference range, verdict or clinical number passes through, and the product owns the words. Of the ten provenance rules in Trends and uncertainty, rules 22 to 31, this component carries two, provenance in plain words at the value (rule 23) and a manufacturer's claim attributed rather than restated (rule 27). The other eight stay the caller's, and it renders a wrong string as readily as a right one. opsinjs ships no source, date, DOI or study. See Safety review.
Accessibility
The audit found no axe violation, missed target size, hidden focus or loss at 320px reflow. Both lines are set at text-opsin-footnote, a rem from the generated ramp and never a px size, in --foreground for the source and --muted-foreground for the date, with no raw colour literal or ramp step. more carries the label and the href together, so a link cannot be added without a label, and an external href adds an off-screen "opens in a new tab". The link is not inside a sentence, so it re-adds --opsin-target-minimum on both axes. See Accessibility. It reflows at 200% text with no fixed height, and min-w-0 with wrap-break-word breaks a long device name.
Residual items.
- The source line, the last-checked time and the fuller-citation link render as loose siblings with no programmatic group binding them. Reading order keeps the association, so this is not an AA failure.
- The "Last checked on" chrome is always English while the date follows the caller's
locale, and when they differ the localised date carries nolangseam yet, per ADR 0005.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves to the link, when there is one | The citation is text, not a tab stop. The link is its only focusable element. |
| Shift+Tab | Moves back out of the link | Reverse order matches visual order. The link is last. |
| Enter | Follows the link | Only when a link is present. An ordinary anchor, so Enter and not Space. |
| Space | Scrolls the page, as it does anywhere else | Nothing here captures Space or activates on it. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| 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 |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from SourceCitationProps in registry/bases/base/source-citation.tsx.
source is typed optional but required by the contract, so the missing state can render. checkedOn is a strict YYYY-MM-DD string or epoch milliseconds, both pinned to UTC. A value that is not a real calendar date is refused, not rendered as a plausible wrong one.