formatRelativeDateTime

Signature

formatRelativeDateTime(value: string, locale?: string | string[], options?: FormatRelativeDateTimeOptions): string

Format the relative time between a plain date-time and a reference date-time.

• Auto-picks the display unit based on the distance, unless largestUnit forces one: second under a minute, minute under an hour, hour under a day, then formatRelativeDate’s thresholds — day under 7 days, week under 28, month under 365, year beyond — so a 3-year distance reads “3 years ago”.
• Compatibility: before 1.16.0 week, month and year were never auto-picked (“1,096 days ago”). Pass largestUnit: "day" to keep a day count.
• largestUnit is one of the seven units from "second" to "year", singular or plural. Any other value returns "".
• options must be an object or omitted: null or any other primitive returns "", as Temporal’s GetOptionsObject rejects it.

Parameters

Parameter	Type	Description
value	string	ISO date-time string to format
locale	string | string[]	optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)

Options

options

How the distance is measured, rounded and worded

Options for formatRelativeDateTime: the reference date-time, the display unit, the rounding and the wording.

import type { FormatRelativeDateTimeOptions } from "@northguild/gmt";

Option	Type	Default	Description
largestUnit?	"years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | RelativeDateTimeUnit (RelativeDateTimeUnit)	None. The unit is picked from the distance.	The unit the distance is written in, whatever its size: "second", "minute", "hour", "day", "week", "month" or "year", singular or plural. Any other value returns "". Omitted, the unit is picked from the distance: second under a minute, minute under an hour, hour under a day, 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

the formatted relative-time string, or "" on invalid input

Types

RelativeDateTimeUnit

Full 7-member RelativeUnit for PlainDateTime-based formatting. Covers the complete set of Intl.RelativeTimeFormat units supported by Temporal, excluding quarter.

import type { RelativeDateTimeUnit } from "@northguild/gmt";

"year" | "month" | "week" | "day" | "hour" | "minute" | "second"

Related types

• RelativeTimeFormatOptions
• RelativeRoundingMethod

Examples

import { formatRelativeDateTime } from "@northguild/gmt/plain/format";

formatRelativeDateTime("2026-03-17T09:00:00", "en-GB", { style: "long", reference: "2026-03-17T06:00:00" }) // "in 3 hours"

valuelocale ?

output

 

Source

plain/format/formatRelativeDateTime.ts