Handling Timezones in JavaScript — Intl API and Best Practices

Handling Timezones in JavaScript

JavaScript's native Date object has limited timezone support, but the Intl API and upcoming Temporal API provide powerful timezone handling capabilities.

The Date Object and UTC

JavaScript Date stores time as milliseconds since the Unix epoch (January 1, 1970 UTC). It has no concept of timezones internally — all values are UTC.

const date = new Date("2024-03-15T14:30:00Z");
date.getTime();        // 1710513000000 (always UTC)
date.toISOString();    // "2024-03-15T14:30:00.000Z" (always UTC)
date.toString();       // Local timezone string (varies by system)

Intl.DateTimeFormat — The Standard Approach

Intl.DateTimeFormat is the built-in way to display dates in specific timezones:

const date = new Date("2024-03-15T14:30:00Z");

// Display in Tokyo
new Intl.DateTimeFormat("en-US", {
  timeZone: "Asia/Tokyo",
  dateStyle: "full",
  timeStyle: "long",
}).format(date);
// "Friday, March 15, 2024 at 11:30:00 PM JST"

// Display in New York
new Intl.DateTimeFormat("en-US", {
  timeZone: "America/New_York",
  dateStyle: "full",
  timeStyle: "long",
}).format(date);
// "Friday, March 15, 2024 at 10:30:00 AM EDT"

Getting All Supported Timezones

// Available in modern browsers (Chrome 99+, Firefox 93+, Safari 15.4+)
const allTimezones = Intl.supportedValuesOf("timeZone");
console.log(allTimezones.length);  // ~400+ IANA timezone IDs

Extracting Parts

const formatter = new Intl.DateTimeFormat("en-US", {
  timeZone: "Asia/Kolkata",
  timeZoneName: "longOffset",
});

const parts = formatter.formatToParts(new Date());
const offset = parts.find(p => p.type === "timeZoneName")?.value;
// "GMT+5:30"

The Temporal API (Stage 3 Proposal)

The upcoming Temporal API provides first-class timezone support:

// Future API (not yet available in all browsers)
const zdt = Temporal.ZonedDateTime.from({
  year: 2024,
  month: 3,
  day: 15,
  hour: 14,
  minute: 30,
  timeZone: "America/New_York",
});

zdt.toString();
// "2024-03-15T14:30:00-04:00[America/New_York]"

zdt.withTimeZone("Asia/Tokyo").toString();
// "2024-03-16T03:30:00+09:00[Asia/Tokyo]"

Common Pitfalls

1. new Date("2024-03-15") is parsed as UTC, but new Date("2024-03-15T00:00:00") is parsed as local time
2. getTimezoneOffset() returns the offset in minutes with an inverted sign (UTC-5 returns +300)
3. Date has no method to "convert" to another timezone — use Intl.DateTimeFormat instead