formatRelativeZoned

Signature

formatRelativeZoned(value: string, locale?: string | string[], options?: FormatRelativeZonedOptions): string

Format the relative time between a zoned date-time and a reference instant.

• 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	ZonedDateTime ISO string to format
locale	string | string[]	optional: BCP 47 locale tag, or a preference list of tags (ECMA-402)

Options

options

optional settings for the wording, the display unit, rounding and the reference moment

Options for formatRelativeZoned: how the phrase is worded, the unit it counts in, how the count rounds and the moment the distance is measured from.

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

Option	Type	Default	Description
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”).
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.
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 | number	The current instant, read in value’s time zone.	The instant the distance is measured from, as a zoned ISO string, a UTC ISO string or a numeric epoch in milliseconds. The distance is the exact time between the two instants; the reference’s time zone only anchors how months and years are counted, which is its own zone for a zoned string and value’s zone for a UTC string or an epoch. Any other value returns "".

Returns

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

Related types

• RelativeUnit
• RelativeRoundingMethod

Examples

import { formatRelativeZoned } from "@northguild/gmt/zoned/format";

formatRelativeZoned("2023-12-29T00:00:00+00:00[UTC]", "en-US", { reference: "2024-02-29T00:00:00+00:00[UTC]" }) // "2 months ago"

valuelocale ?

output

 

Source

zoned/format/formatRelativeZoned.ts