formatTimeZoneName

Signature

formatTimeZoneName(timeZone: string, locale: string, options?: FormatTimeZoneNameOptions): string

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

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). Default “long”.
• “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.

Parameters

Parameter	Type	Description
timeZone	string	IANA timeZone identifier
locale	string	BCP 47 locale tag (e.g. “en-US”)

Options

options

Option	Type	Default
style?	TimeZoneNameStyle	—

Returns

localized zone name, or “” on invalid input

Related types

• FormatTimeZoneNameOptions

Examples

formatTimeZoneName("America/New_York", "en-US", { style: "shortGeneric" }) // "ET"
formatTimeZoneName("America/New_York", "en-US", { style: "longGeneric" }) // "Eastern Time"
formatTimeZoneName("America/New_York", "en-US", { style: "shortOffset" }) // "GMT-4" or "GMT-5", depending on the current date
formatTimeZoneName("Asia/Tokyo", "ja-JP", { style: "longGeneric" }) // "日本標準時"
formatTimeZoneName("Invalid/Zone", "en-US") // ""
formatTimeZoneName("America/New_York", "!!!") // ""

Source

zoned/format/formatTimeZoneName.ts