/// Data Display
RelativeTime
An auto-updating "3m ago" timestamp on a real <time> element, with an absolute UTC tooltip.
import { RelativeTime } from "@protocore/pds";Basics
Pass a value — an ISO string, epoch milliseconds, or a Date. It renders a relative label (3m ago) that ticks every 30 seconds so it never goes stale, inside a semantic <time dateTime> element.
Time styles
timeStyle picks the representation: "relative" (default), "absolute" for the fixed UTC timestamp, or "both" side by side. The absolute form always renders on the server; the relative label swaps in after mount so hydration stays clean.
| relative | |
| absolute | |
| both |
When to use it
RelativeTime is for any "when" a user reads at a glance — last deploy, message age, block time, activity feeds. The relative label conveys recency instantly, while the absolute UTC value sits in the tooltip (and in timeStyle="both") for precision.
Because the relative part depends on "now", it is hydration-suppressed and only appears after the client clock is available — the server renders the absolute value, so there's no mismatch. Use "absolute" when the exact instant matters more than recency (audit logs, legal timestamps). Pair it with Timeline for a vertical event history.
Usage
Do
- Pass a machine value (ISO/epoch/Date) and let the component format it.
- Use the default relative style for feeds and "last updated" affordances.
- Use `"absolute"` or `"both"` where the exact instant is legally or operationally important.
- Trust it in server components — the absolute value renders SSR-safe.
Don't
- Don't pre-format the date to a string and pass that — it can't tick or tooltip.
- Don't assume local time; the absolute form is fixed to UTC by design.
- Don't use relative-only for timestamps that must be unambiguous in an export.
- Don't wrap it in your own `<time>` — it already renders one.
Accessibility
- Renders a semantic `<time>` with a machine-readable `dateTime` (ISO) attribute.
- The absolute UTC value is always available via the `title` attribute, even in relative mode.
- The live-ticking relative label uses `suppressHydrationWarning` so SSR and client agree; an unparseable value renders the literal input with an explanatory `title`.
RelativeTime props
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | — | |
style | CSSProperties | — | Standard inline style, forwarded to the `<time>` element. |
timeStyle | enum | relative | Which representation(s) to render: relative label, absolute UTC timestamp, or both side by side. |
value * | string | number | Date | — | The instant to describe — ISO string, epoch milliseconds, or a `Date`. |