formatRelativeDate

Playground

valuelocale

call

result

 

Signature

formatRelativeDate(value: string, locale?: string, options?: FormatRelativeDateOptions): string

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

Format 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 largestUnit forces one.
• roundingMethod controls how the distance rounds to the display unit.

Parameters

Parameter	Type	Description
value	string	ISO date string to format
locale	string	optional: BCP 47 locale tag

Options

options

Option	Type	Default
style?	"long" | "short" | "narrow"	—
numeric?	"always" | "auto"	—
largestUnit?	RelativeUnit	—
roundingMethod?	RelativeRoundingMethod	—
reference?	string	—

Returns

the formatted relative-time string, or “” on invalid input

Related types

• FormatRelativeDateOptions

Examples

formatRelativeDate("2026-01-15", "en-US", { reference: "2026-04-15" }) // "3 months ago"
formatRelativeDate(value, "en-US", { roundingMethod: "floor" }) // rounds toward the earlier boundary
formatRelativeDate("not-a-date") // ""

Source

plain/format/formatRelativeDate.ts