useFormatRelativeTime

Pass a Duration object and get back a human-readable string. Backed entirely by the browser’s Intl.RelativeTimeFormat API — no third-party dependency required.

The hook automatically picks the most significant unit from the Duration object: years first, then months, then weeks, then days. It uses numeric: 'auto', which emits natural-language expressions wherever a locale has them — words like “yesterday”, “today”, “tomorrow”, “last week” — instead of always emitting a numeric value.

Durations at a glance

Every supported duration value rendered for the selected locale.

Usage

The hook returns a stable format function (memoised with useCallback). Call it anywhere in your render with a Duration object.

import {useFormatRelativeTime} from '@staffbase/design/hooks';

const TimeAgo = ({date}: {date: Date}) => {
  const locale = navigator.language; // or from your i18n context
  const format = useFormatRelativeTime(locale);

  const diffMs = date.getTime() - Date.now();
  const diffDays = Math.round(diffMs / (1000 * 60 * 60 * 24));

  return <time dateTime={date.toISOString()}>{format({days: diffDays})}</time>;
};

Unit priority

The hook resolves the most significant non-zero unit top-down. Provide only the units you want to consider:

const format = useFormatRelativeTime('en-US');

format({years: -1, months: -3, days: -10}); // "last year" — years wins
format({months: -3, days: -10}); // "3 months ago" — months wins
format({weeks: -1, days: -10}); // "last week" — weeks wins
format({days: -3}); // "3 days ago"
format({days: 0}); // "today"

API reference

useFormatRelativeTime(locale)

Returns a format(duration) function. The Duration object accepts optional years, months, weeks, and days numbers; positive values are in the future, negative in the past.