date-fns-tz

date-fns-tz provides time zone support for date-fns v3.0.0 by leveraging the native browser Intl API. This approach avoids including large time zone data bundles in your code.

Key details:

• Compatibility: Works in modern browsers and Node.js. For older environments, use an Intl polyfill.
• Time Zone Specification: You can use IANA time zone names (e.g., America/New_York) or offsets (e.g., -0200, +04:00). If a polyfill is not used, IANA names are not supported.
• Peer Dependency: date-fns is a required peer dependency.

The library supports both CommonJS and native ESM imports. The exports field in package.json ensures the correct entry point is used based on your project type. Ensure your package.json has the type property set to either module (for ESM) or commonjs.

Note: Even in ESM projects, some date-fns imports may resolve to CommonJS until date-fns provides native ESM support.

This library relies on the Intl API. It works out-of-the-box on iOS (React Native) and Android with Hermes.

If your Android project does not use Hermes, you must ensure the Intl API is available by updating your android/app/build.gradle file to use the intl flavor of JSC:

- def jscFlavor = 'org.webkit:android-jsc:+'
+ def jscFlavor = 'org.webkit:android-jsc-intl:+'

Time zone names are generated via the Intl API. For the best results when using tokens like zzz or zzzz, provide a locale from date-fns/locale in the options object.

import { format, toZonedTime } from 'date-fns-tz'
import { enGB } from 'date-fns/locale/en-GB'

const date = new Date('2014-10-25T10:46:20Z')
const parisDate = toZonedTime(date, 'Europe/Paris')

format(parisDate, 'yyyy-MM-dd HH:mm:ss zzzz', {
  timeZone: 'Europe/Paris',
  locale: enGB,
})
// 2014-10-25 10:46:20 Central European Summer Time

Returns a Date object that, when formatted, represents the local time of the specified time zone from a given UTC time. This is useful when you have a UTC timestamp from a server but need to initialize a UI component (like a date picker) with the time as it appears in a specific target time zone.

Signature: toZonedTime(date: Date|Number|String, timeZone: String): Date

An invalid date string or time zone will result in an Invalid Date.

import { toZonedTime } from 'date-fns-tz'

const { isoDate, timeZone } = fetchInitialValues() // 2014-06-25T10:00:00.000Z, America/New_York

const date = toZonedTime(isoDate, timeZone) // In June 10am UTC is 6am in New York (-04:00)

renderDatePicker(date) // 2014-06-25 06:00:00 (in the system time zone)
renderTimeZoneSelect(timeZone) // America/New_York

Given a date and a time zone, fromZonedTime returns a Date object representing the equivalent UTC time. This is useful when receiving a local date/time from a user input (like a date picker) and needing to convert it to UTC for server storage.

Signature: fromZonedTime(date: Date|Number|String, timeZone: String): Date

An invalid date string or time zone will result in an Invalid Date.

import { fromZonedTime } from 'date-fns-tz'

const date = getDatePickerValue() // e.g. 2014-06-25 10:00:00 (picked in any time zone)
const timeZone = getTimeZoneValue() // e.g. America/Los_Angeles

const utcDate = fromZonedTime(date, timeZone) // In June 10am in Los Angeles is 5pm UTC

postToServer(utcDate.toISOString(), timeZone) // post 2014-06-25T17:00:00.000Z, America/Los_Angeles

The toDate function parses a string into a Date object. If the date string contains an offset (e.g., +04:00), that offset takes precedence. If the string lacks an offset, you can provide an IANA time zone name via the timeZone option to define the context of the date/time string.

An invalid date string or time zone will result in an Invalid Date.

import { toDate, toZonedTime, format } from 'date-fns-tz'

// 1. Using offset in string (precedence over timeZone option)
const parsedDate = toDate('2014-10-25T13:46:20+04:00')

// 2. Using timeZone option when no offset is present in the string
const bangkokDate = toDate('2014-10-25T13:46:20', { timeZone: 'Asia/Bangkok' })
const zonedBangkok = toZonedTime(bangkokDate, 'Asia/Bangkok')
format(zonedBangkok, 'yyyy-MM-dd HH:mm:ssxxx', { timeZone: 'Asia/Bangkok' }) // 2014-10-25 13:46:20+07:00

The toDate function may throw the following errors:

• TypeError: Thrown if fewer than 1 argument is provided.
• RangeError: Thrown if options.additionalDigits is not 0, 1, or 2.

If the input is null or cannot be parsed into a valid date, the function returns an Invalid Date object (a Date instance where isNaN(date.getTime()) is true) rather than throwing.