RelativeTime
Displays a date as a localized phrase relative to now, auto-updating
Category: display · WCAG 2.2-AA · time, date, relative, i18n, display
States
- default
Props
| Prop | Type | Default | Description |
|---|---|---|---|
date | Date | number | string | — | The date to render relative to now. |
sync | boolean | true | When true, updates the relative time as it elapses. |
now | number | — | Override "now" (ms); disables the interval. Pass a serialized server timestamp under SSR for a byte-deterministic render. |
format | Intl.RelativeTimeFormatOptions | — | Intl.RelativeTimeFormat options controlling the output. |
When to use
- Showing how long ago something happened in human terms ("3 minutes ago")
- Timestamps in feeds, comments, and activity logs where recency matters more than precision
- Anywhere a self-updating relative time is friendlier than an absolute date
When not to use
- Precise timestamps in tables or audit logs — use formatDate for an exact, sortable value
- Dates far in the past/future where "2 years ago" is less useful than the actual date
How to build an accessible RelativeTime in React →
Examples
Basic
<RelativeTime date={post.createdAt} />Natural language
<RelativeTime date={date} format={{ numeric: "auto" }} />Static (no ticking)
<RelativeTime date={date} sync={false} />SSR deterministic
Relative text is clock-dependent, so it is hydration-safe by default (the server text is kept and corrected on the client). Pass a serialized server timestamp via `now` when you need identical server/client output with no post-hydration correction.
<RelativeTime date={date} now={serverNow} />Related components
- Stat — Use alongside Stat to timestamp a metric’s last update