The date to format, as a Date or ISO 8601 string.
Maximum distance from now, in milliseconds, for relative formatting. When the date is closer than this (e.g. within 24 hours), the result is relative ("5 minutes ago"); at or beyond it, a locale date string is used instead. Defaults to 24 hours. Pass Infinity to always use relative formatting.
Options for Intl.RelativeTimeFormat (numeric, style). Controls phrasing (e.g. "yesterday" vs "1 day ago") and output length (e.g. "1 minute ago" vs "1 min. ago"). Defaults to { numeric: "always", style: "long" }.
Options for Intl.DateTimeFormat when the date falls outside relativeFormatThreshold. Defaults to numeric year, month, and day — avoiding two-digit years produced by dateStyle: "short" in locales such as en-US.
Optional Private__locale: stringUsed for testing.
A locale-aware string: relative time when within relativeFormatThreshold, otherwise a formatted date from toLocaleDateString.
relativeTime(new Date(Date.now() - 1_000 * 60)); // "1 minute ago"
relativeTime(new Date(Date.now() + 1_000 * 60 * 5)); // "in 5 minutes"
relativeTime("2026-01-06T12:00:00.000Z"); // accepts ISO 8601 strings
relativeTime(new Date(Date.now() - 1_000), undefined, { numeric: "auto" }); // locale-dependent phrasing
relativeTime(new Date(Date.now() - 1_000 * 60), undefined, { style: "short" }); // "1 min. ago"
relativeTime(new Date(Date.now() - 1_000 * 60 * 60 * 48)); // locale date string (beyond default 24h threshold)
relativeTime(new Date(Date.now() - 1_000 * 60 * 60 * 24 * 365), Infinity); // always relative
Formats a date as relative time when it is within
relativeFormatThresholdof now, otherwise as a locale-aware date string.