formatTimeZoneName

Signature

formatTimeZoneName(timeZone: string, locale: string | string[], options?: FormatTimeZoneNameOptions): string

Return the localized display name for an IANA timeZone.

• options.style covers every Intl.DateTimeFormatOptions timeZoneName value: “short” (EST), “long” (Eastern Standard Time), “shortOffset” (GMT-5), “longOffset” (GMT-05:00), “shortGeneric” (ET), “longGeneric” (Eastern Time).
• “short”/“long”/“shortOffset”/“longOffset” name the zone’s current offset — for a DST-observing zone the label flips between standard and daylight names depending on when this is called, since there’s no instant parameter to pin it to (this matches how Intl.DateTimeFormat.prototype.format() itself defaults to “now” when called with no argument). “shortGeneric”/“longGeneric” are season-independent (e.g. “ET”, “Eastern Time”) and don’t have this issue — prefer them for a name that won’t change twice a year.
• Output depends on runtime ICU data.
• Returns "" for an invalid timeZone or locale.
• 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
timeZone	string	IANA name or a UTC offset to the minute (what isValidTimeZone accepts)
locale	string | string[]	BCP 47 locale tag (e.g. “en-US”), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns ""

Options

options

optional setting for the form of the name

Options for formatTimeZoneName: the form the zone name is written in.

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

Option	Type	Default	Description
style?	"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric" (TimeZoneNameStyle)	"long"	The form of the name, one of Intl.DateTimeFormat’s timeZoneName values. "short" and "long" give the abbreviated or full name and "shortOffset" and "longOffset" the UTC offset, all four for the offset in effect now. "shortGeneric" and "longGeneric" give a name that does not change with daylight saving.

Returns

localized zone name, or "" on invalid input

Types

TimeZoneNameStyle

Name style for formatTimeZoneName, mirroring Intl.DateTimeFormatOptions’s timeZoneName values.

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

"long" | "short" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric"

Examples

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

formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"

locale

output

 

Source

zoned/format/formatTimeZoneName.ts