Working with Time Zones in JavaScript

Working with Time zones is often tricky. It doesn’t have to be.

The JavaScript APIs for dealing with dates is really quite fiddly, under-developed and under-documented. Here are some simple tips.

If at all possible, you should use a plugin such as date-fns or moment.js. They make your life so much easier and you can focus on what you care about.

However, if you must work in plain JavaScript, keep reading.

Convert to UTC

A good option is to always convert a time to Coordinated Universal Time (aka UTC) and offset from there.

The easiest way to get a UTC string is to use one of the following functions:

let date = new Date();
date.toLocaleString("en-us", {timeZone: "utc"}); 
// returns "3/15/2021, 7:22:36 PM"
date.toLocaleDateString("en-gb", {timeZone: "utc"})
// returns "15/03/2021"
date.toLocaleTimeString([], {timeZone: "utc"})
// returns "19:22:36"
date.toISOString(); 
// returns "2021-03-15T19:22:36.245Z"

Note: the “Z” in the ISO string indicates “Zulu” time, also known as UTC.

There are plenty of options for the constructor, check the MDN Web Docs for more details.

Pre-Encoded Time

If you are given a date (say, from a JSON file) that’s already timezone encoded, you can pass it into the Date constructor as-is.

In the example below, we have a time set to 5:30 PM in San Francisco, aka Pacific Time (GMT -7).

let date = new Date("2021-03-15T17:30:00-0700");

Note: Do not use constructor arguments with time zone abbreviations like:
new Date("Mar 15 2021 19:00:00 EST")
as it’s too browser-dependent. “EST” can refer to 3 different time zones.

Set Time Zone Using Identifiers

Browsers are not required to recognise any timezone except for UTC.

In practice, most modern browsers support IANA time zone identifiers, such as 'America/New_York' (note the underscore). Source

A full list of time zone identifiers is available on Wikipedia.

let date = new Date("2021-03-15T19:22:36.245-0700");
date.toLocaleString("en-us", {timeZone: "America/New_York"});
// returns "3/15/2021, 10:22:36 PM"

Set Time Zone Using Offset Hours

Here’s a simple function that does it for the current time:

function convertTime(date, offset) {
  if (offset) {
    offset = parseFloat(offset);
  } else {
    offset = 0;
  }
  
  date.setHours(date.getHours() + (date.getTimezoneOffset() / 60) + offset);
  date.setMinutes(date.getMinutes() + (date.getTimezoneOffset() / 60) + offset % 1 * 60);
  return date.toTimeString();
}

Quick explainer of what I’m doing in setHours:

• Get the current hours
• Remove the current offset (this gets us to UTC)
• Add the offset (e.g. “5”) will add 5 hours and “-3” will subtract 3 hours.

Example Usage

• convertTime(new Date()); will get the current time in UTC.
• convertTime(new Date(), -7); will get the current time in San Francisco.
• convertTime(new Date(), 13); will get the current time in New Zealand.