formatCalendarUtc

Signature

formatCalendarUtc(value: string, locale?: string | string[], options?: FormatCalendarUtcOptions): string

Format a UTC ISO string as a relative day label plus time-of-day, e.g. “Tomorrow at 2:30 PM” — the UTC counterpart of formatCalendar. See that function’s JSDoc for the day-label/threshold/connector design; this variant compares calendar days and renders the clock time in timeZone.

• options must be an object or omitted: null returns "", as Temporal’s GetOptionsObject rejects it.
• An offset with seconds (-00:44:30) returns "". Intl.DateTimeFormat takes a time zone identifier only: constructing one with an offset that has seconds throws (ECMA-402, the DateTimeFormat construction step “If parseResult contains more than one MinuteSecond Parse Node, throw a RangeError exception”). Pass the IANA name.

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 time zone and the time style

Options for formatCalendarUtc: the instant the day label is measured from, the time zone the days and the clock time are read in, and the width of the time-of-day half.

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

Option	Type	Default	Description
timeZone?	string	"UTC"	The time zone used for both the calendar-day comparison and the rendered clock time: an IANA name, a UTC offset to the minute (what isValidTimeZone accepts), or "local" for the system time zone. An unknown zone returns "", as ECMA-402 throws RangeError for it.
timeStyle?	"long" | "short" | "medium" | "full"	"short"	The length of the time-of-day part, as the timeStyle of Intl.DateTimeFormat. "short" writes hours and minutes, "medium" adds seconds, "long" adds the short time zone name (“EDT”) and "full" the long one (“Eastern Daylight Time”). Any other value returns "".
reference?	string	The current date and time.	The moment the day label is measured from, as an ISO string in the same form as the value being formatted. A value on the same calendar day reads “today”, one on the next day “tomorrow”.

Returns

the formatted calendar string, or "" on invalid input

Related types

• CalendarOptions

Examples

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

formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"

valuelocale ?

output

 

Source

utc/format/formatCalendarUtc.ts