Skip to content
helpers4helpers4

formatInTimezone

Formats a date in a specific IANA timezone using Intl.DateTimeFormat.

Returns null if the date or timezone is invalid.

Available since v2.0.0

Import

Section titled “Import”
import { formatInTimezone } from '@helpers4/date';

Signature

Section titled “Signature”
formatInTimezone(date: DateLike, tz: string, options: FormatInTimezoneOptions): string | null

Parameters

Section titled “Parameters”
ParameterTypeDescription
dateDateLikeThe date to format
tzstringIANA timezone identifier (e.g. 'Asia/Tokyo')
optionsFormatInTimezoneOptionsOptional locale and format configuration

Returns

Section titled “Returns”

string | null — A formatted date string, or null

Examples

Section titled “Examples”

formatInTimezone

Section titled “formatInTimezone”
formatInTimezone('2025-01-19T12:00:00Z', 'Asia/Tokyo')
// => "1/19/2025, 9:00:00 PM" (en-US default)

formatInTimezone('2025-01-19T12:00:00Z', 'Europe/Paris', {
  locale: 'fr-FR',
  formatOptions: { dateStyle: 'long', timeStyle: 'short' },
})
// => "19 janvier 2025, 13:00"
Section titled “Related Types”

FormatInTimezoneOptions

Section titled “FormatInTimezoneOptions”

Options for formatInTimezone.

interface FormatInTimezoneOptions {
  formatOptions?: DateTimeFormatOptions;
  locale?: string;
}

DateLike

Section titled “DateLike”

A value that can be converted to a Date.

  • Date — used as-is (validated for Invalid Date)
  • number — treated as a timestamp (seconds or milliseconds, auto-detected); 0 is treated as invalid and produces null in ensureDate
  • string — parsed via new Date(string)
  • Temporal.Instant | Temporal.ZonedDateTime — read via their epochMilliseconds property
type DateLike = Date | number | string | Temporal.Instant | Temporal.ZonedDateTime

Source

Section titled “Source”

View source on GitHub