formatUtc

Signature

formatUtc(value: string, locale?: string | string[], options?: FormatUtcOptions): string

Format a UTC ISO string as a localized date/time string.

• Returns "" if the input is not a valid UTC string.
• The requested fields and style widths are kept, and era alone still gets the date and time defaults.
• Compatibility: before 1.16.0 some locales and calendars lost a requested width (ja-JP with the japanese calendar and month: "long" gave "R6/2"), a long/full timeStyle replaced the dateStyle width, era alone dropped the time, and timeZoneName alone without includeTimeZoneName returned "". Pass the fields the old text showed to keep it.
• options null returns "", as ECMA-402’s CoerceOptionsToObject 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 time zone, the zone-name switch and any Intl.DateTimeFormatOptions

Options for formatUtc. Extends Intl.DateTimeFormatOptions; only the added/overridden members are declared here. All Intl.DateTimeFormatOptions (dateStyle, timeStyle, etc.) apply to the time-of-day portion.

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

Option	Type	Default	Description
timeZone?	string	"UTC"	The time zone the value is rendered in: 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.
includeTimeZoneName?	boolean	false	Whether the localized time zone name is appended. When true the value is formatted as Temporal’s ECMA-402 ZonedDateTime format does, which adds a short zone name to the defaults; when false, as the PlainDateTime format does, and timeZoneName is ignored.
…Intl.DateTimeFormatOptions	—	—	Every other field of DateTimeFormatOptions, as ECMA-402 defines it.

Returns

the formatted date/time string, or "" on invalid input

Examples

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

formatUtc("2026-03-16T18:30:00Z") // "3/16/2026, 6:30:00 PM"

valuelocale ?

output

 

Source

utc/format/formatUtc.ts