HyRelativeTime

Usage examples on this page are written for Lit / plain HTML (<hy-relative-time>). The same component ships as HyRelativeTime in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

Renders a date as a relative phrase ("3 minutes ago", "in 2 days"), auto-updating as time passes.

Wraps a native <time datetime> so the precise timestamp is always in the DOM for screen readers and tooling. Phrasing comes from Intl.RelativeTimeFormat; the elapsed-duration math runs on Temporal (via the shared ensureTemporal() gate — native on evergreen engines, polyfilled only on Safari / non-Temporal runtimes) so unit boundaries are calendar-accurate rather than fixed-second approximations.

SSR safety: relative time is non-deterministic, so the server and the first client render emit the absolute date (deterministic), then upgrade to relative on mount — avoiding a hydration mismatch.

Key Features:

• format: long / short / narrow
• sync: self-managing refresh that tightens near, relaxes far, and pauses on document.hidden
• threshold: past a cutoff, fall back to the absolute formatted date
• Past and future tense; locale-aware

When to use

• When something happened recently, where how long ago matters more than the date: a comment, an update, a last sign-in.
• A list that stays open and should keep its times current, with sync.

Do

• Offer the full date nearby, in a tooltip or a detail view.
• Set threshold to switch to a date once the moment is far enough back.

When not to use

• A date someone may cite, as on an invoice, a contract or an audit log: the full date as text.
• Entering a date: hy-date-field, or hy-date-picker to pick from a calendar.
• A countdown to the second: it rounds to the largest whole unit, so it is no timer.
• A sequence of dated events: hy-timeline.

Accessibility: your part

• Put a lead-in before it, such as Edited, Posted or Last synced, so the phrase says what happened then.
• Never place it inside a live region. With sync every update would be announced.
• Where the exact moment matters, show it as text beside the phrase, not only on hover.

Examples

<hy-relative-time date="2026-06-12T10:00:00Z" sync></hy-relative-time>

API

Properties

Property	Attribute	Type	Default	Description
date	date	string | number | undefined	—	The target date — ISO string or epoch ms.
format	format	'long' | 'short' | 'narrow'	'long'	Phrasing granularity.
sync	sync	boolean	false	Auto-refresh as time passes.
threshold	threshold	number | undefined	—	Past this elapsed ms, render the absolute formatted date instead of relative.
locale	locale	string | undefined	—	BCP-47 locale. Unset, the nearest lang (across shadow roots), else the browser's language.
now	—	string | number | Date | undefined	—	Injectable "current time" for deterministic tests / stories. Property-only.

CSS Parts

Part	Description
time	The inner <time> element.