useRelativeTime

(no submodules)

Purpose

useRelativeTime(deltaMs, options?) formats a millisecond delta as a localised relative-time string ("in 5 minutes", "3 hours ago", "il y a 2 jours"). Wraps Intl.RelativeTimeFormat directly with a per-(locale, style, numeric) cache so the formatter constructor is paid once per process per option combination. Memoised on (resolvedLocale, deltaMs, options-hash) so a no-op re-render does not reach into the cache or the formatter.

When the unit option is omitted the hook auto-selects the largest unit whose absolute value is ≥ 1 (per the universal-core formatRelativeTime contract). Pass unit explicitly when a fixed granularity matters — e.g. always render activity timestamps in minutes within the first hour for consistency with a refresh interval.

Features

Auto-selects unit (seconds → years) when unit is omitted.
Forwards style ('long' | 'short' | 'narrow') and numeric ('always' | 'auto').
Per-(locale, style, numeric) cache of Intl.RelativeTimeFormat instances.
Memoised on (locale, deltaMs, options-hash) — no re-format on identical inputs.
Production no-Provider fallback uses 'en-GB' so the hook always returns a real string.
Re-renders on languageChanged via the inherited useLocale subscription.
clearUseRelativeTimeCache() exposed for tests / hot-reload scenarios.

Usage: Basic Example

import { useRelativeTime } from "@suaveplan/react-i18n";

export function PostedAt(props: { readonly postedAt: Date }) {
    const delta = props.postedAt.getTime() - Date.now();
    const formatted = useRelativeTime(delta);
    return <time dateTime={props.postedAt.toISOString()}>{formatted}</time>;
}

Usage: Advanced Example

For activity feeds that update once per second, pin the unit to 'seconds' for the first minute and 'minutes' thereafter. The pattern below shows a row that picks the unit explicitly to avoid stuttering between auto-selected units near boundary thresholds.

import { useRelativeTime } from "@suaveplan/react-i18n";

export function LiveTimestamp(props: { readonly when: Date }) {
    const delta = props.when.getTime() - Date.now();
    const abs = Math.abs(delta);
    const unit = abs < 60_000 ? "seconds" : "minutes";
    const formatted = useRelativeTime(delta, {
        style: "short",
        numeric: "always",
        unit,
    });
    return <span data-live="true">{formatted}</span>;
}

API Reference