formatRelativeDate
Signature
Section titled “Signature”formatRelativeDate(value: string, locale?: string | string[], options?: FormatRelativeDateOptions): stringFormat the relative time between a plain date and a reference date.
- Auto-picks the display unit (day/week/month/year) based on the distance, unless
largestUnitforces one. largestUnitis one of those four units, singular or plural. Any other value returns"".optionsmust be an object or omitted:nullor any other primitive returns"", as Temporal’s GetOptionsObject rejects it.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | ISO date string to format |
locale | string | string[] | optional: BCP 47 locale tag, or a preference list of tags (ECMA-402) |
Options
Section titled “Options”options
How the distance is measured, rounded and worded
Options for formatRelativeDate: the reference date, the display unit, the rounding and the wording.
import type { FormatRelativeDateOptions } from "@northguild/gmt";| Option | Type | Default | Description |
|---|---|---|---|
largestUnit? | "years" | "months" | "weeks" | "days" | RelativeDateUnit (RelativeDateUnit) | None. The unit is picked from the distance. | The unit the distance is written in, whatever its size: "day", "week", "month" or "year", singular or plural. Any other value returns "", a time unit such as "hour" included: a date has no time, and Temporal throws RangeError for a unit outside the units of the type. Omitted, the unit is picked from the distance: day under 7 days, week under 28, month under 365 and year beyond. |
style? | "long" | "short" | "narrow" | "long" | The length of the unit name, as the style of Intl.RelativeTimeFormat: "long" (“in 3 months”), "short" (“in 3 mo.”) or "narrow" (the locale’s most compact form). |
numeric? | "auto" | "always" | "auto" | Whether a distance may be written as a word instead of a number, as the numeric option of Intl.RelativeTimeFormat. "auto" uses the locale’s word where it has one (“yesterday”, “next year”); "always" writes the number every time (“1 day ago”). |
roundingMethod? | "ceil" | "floor" | "round" (RelativeRoundingMethod) | "round" | The way a fractional distance becomes the whole number displayed: "round" goes to the nearest whole number, "floor" down and "ceil" up. It applies to the signed value, where a past distance is negative, so "floor" turns −1.5 hours into “2 hours ago”. |
reference? | string | The current date and time. | The moment the distance is measured from, as an ISO string in the same form as the value being formatted. |
Returns
Section titled “Returns”the formatted relative-time string, or "" on invalid input
RelativeDateUnit
Section titled “RelativeDateUnit”Narrow RelativeUnit for PlainDate-based formatting. Excludes hour, minute, and second because PlainDate has no time component.
import type { RelativeDateUnit } from "@northguild/gmt";"year" | "month" | "week" | "day"Related types
Section titled “Related types”Examples
Section titled “Examples”import { formatRelativeDate } from "@northguild/gmt/plain/format";
formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"