formatRelativeUtc

Signature

formatRelativeUtc(value: string, locale?: string | string[], options?: FormatRelativeUtcOptions): string

Format the relative time between a UTC ISO string and a reference instant.

• Picks the display unit from the distance, using formatRelativeDate’s day thresholds past a day, 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 returns "", as Temporal’s GetOptionsObject rejects it.
• Limit at an offset with seconds. A month or a year is measured from reference, placed in the offset’s whole-minute zone and moved by its seconds, and the moved instant must be inside Temporal’s range. So when one is measured and reference is within the offset’s seconds (under a minute) of the last instant Temporal supports (+275760-09-13T00:00:00Z) for an offset east of UTC, or of the first (-271821-04-20T00:00:00Z) for one west, this returns "". An offset to the minute has no such limit.

Parameters

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

Options

options

The reference instant, the display unit, rounding, wording and time zone

Options for formatRelativeUtc: the instant the distance is measured from, the unit it is shown in, how it rounds, and the wording Intl.RelativeTimeFormat uses.

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

Option	Type	Default	Description
largestUnit?	"years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | RelativeUnit (RelativeUnit)	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.
reference?	string	The current instant.	The instant the distance is measured from, as a UTC ISO string. Any other value returns "".
timeZone?	string	"UTC"	The time zone that anchors a calendar unit (week, month or year): an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns "" whatever the unit.
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”.

Returns

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

Related types

• RelativeTimeFormatOptions
• RelativeRoundingMethod
• RelativeUnit

Examples

import { formatRelativeUtc } from "@northguild/gmt/utc/format";

formatRelativeUtc("2026-01-15T14:30:45Z", "en-US", { reference: "2026-04-15T14:30:45Z" }) // "3 months ago"

valuelocale ?

output

 

Source

utc/format/formatRelativeUtc.ts