formatCalendarZoned
Signature
Section titled “Signature”formatCalendarZoned(value: string, locale?: string | string[], options?: FormatCalendarZonedOptions): stringFormat a zoned date-time as a relative day label plus time-of-day, e.g. “Tomorrow at 2:30 PM” — the zoned counterpart of formatCalendar. See that function’s JSDoc for the day-label/threshold/connector design; this variant differs only in reading value’s IANA timezone for both the calendar-day comparison and the rendered clock time.
optionsmust be an object or omitted:nullor any other primitive returns"", as Temporal’s GetOptionsObject rejects it.
Parameters
Section titled “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
Section titled “Options”options
optional settings for the reference moment and the time style
Options for formatCalendarZoned: the moment the day label is measured from and the length of the time-of-day half.
import type { FormatCalendarZonedOptions } from "@northguild/gmt";| Option | Type | Default | Description |
|---|---|---|---|
reference? | string | number | The current instant, read in value’s time zone. | The instant the day label is measured from, as a zoned ISO string, a UTC ISO string or a numeric epoch in milliseconds. Whatever its form, it is converted into value’s own time zone before calendar days are compared, because a day label needs one zone’s wall clock and value’s zone is whose “today” is being described. Any other value returns "". |
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 "". |
Returns
Section titled “Returns”the formatted calendar string, or "" on invalid input
Examples
Section titled “Examples”import { formatCalendarZoned } from "@northguild/gmt/zoned/format";
formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"