---
title: "RelativeTime"
description: "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."
url: "https://opsinjs.pensievelabs.org/docs/components/relative-time"
source: "https://opsinjs.pensievelabs.org/docs/components/relative-time.md"
section: "Components"
status: "shipped"
kind: "component"
category: "health-formatting"
reviewed: "2026-09-20"
reviewer: "engineering"
aliases: ["ago", "timestamp", "last updated", "freshness", "staleness", "time ago", "date display"]
governedBy: ["trends", "numbers", "alerts", "safety-review"]
usedIn: ["daily-logging", "offline-and-stale-data", "sharing-with-a-clinician"]
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="relative-time"
  status="shipped"
  questions="[
  &#x22;The component never ticks or reads the clock, so a surface left open for an hour keeps its first phrase; whether an opt-in re-rendering wrapper belongs is open.&#x22;,
  &#x22;The five event words are English and locale does not translate them, and a prop to supply others would also let a product relabel synced as updated.&#x22;,
  &#x22;The muted stale treatment is unmeasured against the muted fill, the tinted grounds it may share, and under increased contrast, and no preview renders it.&#x22;,
]"
>
  Audited against WCAG 2.2 AA. Clinical review pending.
</StubNotice>

## Usage [#usage]

<ComponentInstall name="relative-time" unbuilt="false" importPath="@/components/ui/relative-time" />

```tsx
import { RelativeTime } from "@/components/ui/relative-time"
```

```tsx
<RelativeTime
  at="2026-03-14T08:12:00+00:00"
  event="measured"
  now={new Date().toISOString()}
  locale="en-GB"
/>
```

## Examples [#examples]

<ComponentPreview name="relative-time" />

### A column of entries [#a-column-of-entries]

Every row names its `event`, and no row passes `staleAfterHours`.

<ComponentPreview name="relative-time-in-a-log-list" kind="example" align="start" />

### Measured and synced are two different facts [#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.

<ComponentPreview name="relative-time-measured-and-synced" kind="example" align="start" />

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

<WhenToUse
  use="[
  &#x22;Saying when a reading was measured, a result was issued, a dose was taken, or data last synced.&#x22;,
  &#x22;Any timestamp a reader will use to judge how much weight to give the thing it is attached to.&#x22;,
  &#x22;Lists of recent entries, where an age is read far faster than two dates side by side.&#x22;,
]"
  avoid="[
  { case: &#x22;The date itself is the information. That is true of an appointment, a deadline and a date of birth.&#x22;, instead: &#x22;value&#x22; },
  { case: &#x22;The reader must act by a certain time and needs the actual date and time.&#x22;, instead: &#x22;care-card&#x22; },
  { case: &#x22;The event is far enough in the past that a relative phrase is less useful than the date.&#x22;, instead: &#x22;value&#x22; },
  { case: &#x22;You are showing a duration rather than a point in time.&#x22;, instead: &#x22;value&#x22; },
  { case: &#x22;The time is being entered rather than displayed.&#x22;, instead: &#x22;field&#x22; },
]"
/>

## Clinical meaning [#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](../health/numbers.mdx) 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](../health/trends.mdx) 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.

<SafetyCallout severity="attention" evidence="opinion">
  Never put a sync time where a measurement time belongs. *Synced 2 minutes ago* above a
  reading taken four months ago is two true statements that together mislead. Render both,
  each with its event word.
</SafetyCallout>

## Accessibility [#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 explicit `locale` or 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.

<KeyboardTable
  name="relative-time"
  rows="[
  {
    keys: &#x22;Tab&#x22;,
    action: &#x22;Skips the timestamp&#x22;,
    notes: &#x22;Not focusable and no keyboard behaviour: it holds no control.&#x22;,
  },
  {
    keys: &#x22;Shift + Tab&#x22;,
    action: &#x22;Skips the timestamp&#x22;,
    notes: &#x22;Same in reverse. The exact date is reached by reading, not operating.&#x22;,
  },
]"
/>

<ContrastReport component="relative-time" />

## Props interface [#props-interface]

<PropsTable name="RelativeTimeProps" />

`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.
