RelativeTime

Usage examples

import { RelativeTime } from '@rookcom/monarch-react';

const NOW = Date.UTC(2026, 10, 3, 12, 0, 0);

const MIN = 60_000;

const HOUR = 60 * MIN;

const DAY = 24 * HOUR;

<div>
  <RelativeTime
    date={NOW - 3 * MIN}
    now={NOW}
    locale="en"
    format="short"
    tooltip={false}
  />
</div>
<div>
  <RelativeTime
    date={NOW - 3 * MIN}
    now={NOW}
    locale="en"
    format="narrow"
    tooltip={false}
  />
</div>
<div>
  <RelativeTime
    date={NOW - DAY}
    now={NOW}
    locale="en"
    numeric="always"
    tooltip={false}
  />
</div>

import { RelativeTime } from '@rookcom/monarch-react';

const NOW = Date.UTC(2026, 10, 3, 12, 0, 0);

const MIN = 60_000;

const HOUR = 60 * MIN;

<div>
  Localised: <RelativeTime date={NOW - 3 * HOUR} now={NOW} locale="de" timeZone="UTC" />
</div>

Purpose

Shows when something happened (or will happen) relative to now, in the reader’s language, while keeping the exact moment one hover or Tab away and machine-readable in datetime.

Design principles

• The exact time is never only in a title: the tooltip opens on hover and on keyboard focus and is linked with aria-describedby.
• Localised by Intl.RelativeTimeFormat and Intl.DateTimeFormat; no hand-written “ago” strings.
• Server rendering is deterministic when you pass now; without it, the client corrects the text after hydration instead of warning.
• Live updates are quiet: the text changes without a live region, so screen readers are not interrupted every minute.

API reference

import { RelativeTime, formatRelativeTime, relativeTimeParts } from '@rookcom/monarch-react';

The ref and native attributes go to the <time> element; className goes to the mn-relative-time wrapper that also holds the tooltip.

formatRelativeTime(date, options) and relativeTimeParts(date, now) are exported for places that need the string, such as table exports or aria-labels.

Generated from the TypeScript declarations of packages/react/src/components/data-display/relative-time.

Properties

date and now accept a Date, epoch milliseconds or an ISO 8601 string.

Variants

States

Interaction behaviour

• Hovering the text or the tooltip keeps the tooltip open; the pointer can move onto it (WCAG 1.4.13).
• With live, the text re-renders every 5 s for the first minute, then every 30 s, 5 min and 1 h as it ages; a number sets a fixed interval.
• Passing now freezes the reference time, which turns live off.

Keyboard support

Accessibility

Role

time (with a role="tooltip" description)

Accessible name

The relative text; the absolute time is its description through aria-describedby.

• datetime carries the ISO 8601 instant for machines and assistive technology.
• The tooltip shows on :focus-visible, not only on hover, and can be dismissed with Escape.
• Use tooltip={false} in dense lists to avoid a tab stop per row when the exact time is available elsewhere.

Responsive behaviour

• The text does not wrap. The tooltip is at most 18rem wide and never wider than the viewport minus 2rem.
• The tooltip is positioned with CSS above the text; inside a container that clips overflow it can be cut off, so give such containers room or use tooltip={false}.

Theme support

• The tooltip uses the inverse surface tokens, like Tooltip, so it reads in light, dark and more-contrast themes.
• The dotted underline uses the current text colour at reduced opacity.
• The tooltip fade is removed under reduced motion.

Do and don't

Related components

• Tooltip: Rich supplementary content on hover and focus.
• ActivityTimeline: Planned feed that shows a RelativeTime per event.
• DescriptionList: Label and value pairs such as “Last updated”.
• DatePicker: Planned input for choosing a date rather than showing one.

Dependencies

Testing coverage

• Unit selection rounds before rolling over (59.6 min reads “1 hour ago”).
• Formats with Intl.RelativeTimeFormat, including numeric, format and other locales.
• Renders <time datetime> and an absolute tooltip linked by aria-describedby.
• Accepts ISO strings, epoch numbers and Date objects.
• Is a tab stop; Escape dismisses the tooltip and blur resets it.
• tooltip={false}, absoluteAfter, timeZone and invalid dates.
• Live updates tick with fake timers; no ticking without live.
• Forwards the ref and calls consumer handlers.
• Server rendering with now, and hydration with a different client clock without errors.

Tests: packages/react/src/components/data-display/relative-time