Components
RelativeTime
When something happened, written the way people say it. The exact date and time stay in reach, and explicit words appear past the staleness boundary.
Usage
pnpm dlx shadcn@latest add @opsinjs/relative-time
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 { RelativeTime } from "@/components/ui/relative-time"<RelativeTime
at="2026-03-14T08:12:00+00:00"
event="measured"
now={new Date().toISOString()}
locale="en-GB"
/>Examples
relative-time · base base · style base-lyraOpen under the product themeA column of entries
Every row names its event, and no row passes staleAfterHours.
relative-time-in-a-log-list · base base · style base-lyraOpen under the product themeimport { RelativeTime } from "@/components/ui/relative-time"
const NOW = "2026-03-14T11:12:00+00:00"
const ENTRIES = [
{ subject: "First example measurement", at: "2026-03-14T09:40:00+00:00", event: "measured" },
{ subject: "Second example measurement", at: "2026-03-13T21:05:00+00:00", event: "recorded" },
{ subject: "Third example measurement", at: "2026-03-13T07:30:00+00:00", event: "measured" },
{ subject: "Fourth example measurement", at: "2026-03-10T18:15:00+00:00", event: "measured" },
] as const
export default function RelativeTimeInALogList() {
return (
<ul
role="list"
className="m-0 flex w-full max-w-md list-none flex-col gap-opsin-2 p-0"
>
{ENTRIES.map((entry) => (
<li
key={entry.subject}
className="flex flex-wrap items-baseline justify-between gap-opsin-2 border-b border-border py-opsin-2 text-opsin-body"
>
<span>{entry.subject}</span>
<RelativeTime
at={entry.at}
event={entry.event}
now={NOW}
locale="en-GB"
className="text-opsin-footnote"
/>
</li>
))}
</ul>
)
}Measured and synced are two different facts
Both lines are true. The event prefix keeps a sync time from lending its reassurance
to a reading taken eleven days earlier.
relative-time-measured-and-synced · base base · style base-lyraOpen under the product themeimport { RelativeTime } from "@/components/ui/relative-time"
const NOW = "2026-03-14T11:12:00+00:00"
export default function RelativeTimeMeasuredAndSynced() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-3 rounded-lg border border-border p-opsin-4">
<div className="flex flex-col gap-opsin-1">
<span className="text-opsin-headline">Example measurement</span>
<RelativeTime
at="2026-03-03T07:45:00+00:00"
event="measured"
now={NOW}
locale="en-GB"
className="text-opsin-footnote"
/>
</div>
<RelativeTime
at="2026-03-14T11:09:00+00:00"
event="synced"
now={NOW}
locale="en-GB"
className="text-opsin-footnote"
/>
</div>
)
}When to use it
Use it when
- Saying when a reading was measured, a result was issued, a dose was taken, or data last synced.
- Any timestamp a reader will use to judge how much weight to give the thing it is attached to.
- Lists of recent entries, where an age is read far faster than two dates side by side.
Do not use it when
- The date itself is the information. That is true of an appointment, a deadline and a date of birth.Use
valueinstead. - The reader must act by a certain time and needs the actual date and time.Use
care-cardinstead. - The event is far enough in the past that a relative phrase is less useful than the date.Use
valueinstead. - You are showing a duration rather than a point in time.Use
valueinstead. - The time is being entered rather than displayed.Use
fieldinstead.
Clinical meaning
Asserts. That the named event happened at that instant and, past staleAfterHours,
that the product no longer considers the value current. It does not know what was
measured. The phrase rounds down at every rung except the minute floor, but the
staleness verdict uses the exact elapsed time, not the phrase, as
Numbers and units requires.
Never read as. Freshness of the data. Synced 5 minutes ago means the app spoke to
a server, not that the readings are that new, which is why event is required.
Colour axis. Neither. The stale treatment is muted text carried by the words may be out of date, never a status tint on a fact about the clock.
Thresholds. Staleness belongs to the product: no default, no per-event default and
nothing derived from event. Omit staleAfterHours and no stale treatment renders;
supply it and the words appear past the boundary, or wherever it could not be applied,
as Trends and uncertainty asks. The muted treatment reaches
the time element only, so an embedding surface still owes the value's de-emphasis
and a route to refresh.
Accessibility
There is no axe, target-size, focus-visible or 320px reflow issue and no critical or
serious defect in the source. The exact date is always in the accessibility tree and
in print, never behind hover, focus or a disclosure; showAbsolute moves it on screen
only. Staleness is stated in words, never by the muted tone alone, and the words stay
at the surrounding foreground while the phrase recedes. The audit fixed one moderate
item: the log-list example's list-none <ul> lost its list semantics under Safari
with VoiceOver, so the rows read as generic text, and a role="list" now restores the
role with no visual or API change.
Residual items.
- It mounts no live region and owns no timer, so nothing changes at runtime to
announce; a product re-rendering it should add no
aria-live. - No
"use client", effect or clock read, so hydration is safe by determinism. Pass an explicitlocaleor server and browser may differ. - The muted stale treatment's contrast on the muted or tinted grounds it may sit on is unmeasured, and no shipped preview renders the stale state.
- Screen readers in a language other than English are unverified.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the timestamp | Not focusable and no keyboard behaviour: it holds no control. |
| Shift+Tab | Skips the timestamp | Same in reverse. The exact date is reached by reading, not operating. |
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 RelativeTimeProps in registry/bases/base/relative-time.tsx.
at, event and now are required with no defaults. An at without an offset, or an
event outside the five, renders nothing and warns in development. An unparseable now
renders the date alone. absoluteAfterDays defaults to 1; 0 shows the
date at every age. TimeEvent is exported.