HyRelativeTime
Usage examples on this page are written for Lit / plain HTML (
<hy-relative-time>). The same component ships asHyRelativeTimein@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/narrowsync: self-managing refresh that tightens near, relaxes far, and pauses ondocument.hiddenthreshold: past a cutoff, fall back to the absolute formatted date- Past and future tense; locale-aware
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 (defaults to the environment locale). |
now | — | string | number | Date | undefined | — | Injectable "current time" for deterministic tests / stories. Property-only. |
Slots
| Slot | Description |
|---|---|
default | No slots; the element renders its own <time>. |
CSS Parts
| Part | Description |
|---|---|
time | The inner <time> element. |