toLocaleString() function's supported timezones are implementation-specific. Which means that you're better off not relying on
toLocaleString() supporting timezones in the browser.
Getting Started With moment-timezone
Once you install moment-timezone, you can
require() it in and use it like you would use moment.
const moment = require('moment-timezone'); moment().toString();
The moment-timezone API is, for practical purposes, a superset of the moment API. Virtually anything you can do with moment, you can also do with moment-timezone. For example, date formatting:
const moment = require('moment-timezone'); moment().format('YYYYMMDD HH:mm');
However, moment-timezone adds a
moment.tz() that you can use to create a
new moment object with a custom timezone. For example, here's how you can
create a moment object representing the current time in Longyearbyen, Norway.
- 'America/New_York': US Eastern time
- 'America/Los_Angeles': US Pacific time
- 'Europe/London': UK time
One of the main reasons to use moment-timezone is to convert existing dates from a standardized format to a certain timezone. For example, given a Unix timestamp, you can convert that timestamp to its corresponding time in London, regardless of your machine's local time.
You can convert a Unix timestamp to a nicely formatted string in a given
timezone by passing 2 parameters to
moment.tz(1591716176 * 1000, 'Europe/London').format('YYYYMMDD HH:mm');
moment.tz(new Date(), 'Europe/London').format('YYYYMMDD HH:mm');
moment.tz(new Date(), 'Europe/London').format('YYYYMMDD HH:mm z');
Note that 'z' outputs BST, not Europe/London. The IANA timezone Europe/London encodes daylight savings time rules. That means, if you pass Europe/London to moment-timezone, the 'z' option can output 'GMT' or 'BST' depending on daylight savings.
moment.tz(new Date('2020-01-02'), 'Europe/London').format('YYYYMMDD HH:mm z');
moment.tz() supports the same parameters as
plus the addition of a timezone parameter. For example, the below code
parses the date string '2020/01/02' with the given format and timezone,
giving you a moment object representing midnight on January 2, 2020
moment.tz('2020/01/02', 'YYYY/MM/DD', 'Europe/London').format('YYYYMMDD HH:mm z'); moment.tz(new Date('2020/01/02'), 'Europe/London').format('YYYYMMDD HH:mm z');
tz() vs Method
A common cause of confusion is that, in addition to the static
function, moment-timezone also adds a
tz() method to moment instances.
This lets you change the timezone of a moment instance.
moment(new Date('2020-01-02')).tz('America/Los_Angeles').format('YYYYMMDD HH:mm z');
In many cases, using the static function
moment.tz() and the
gives you the same result. However, they can give different results when parsing
For example, if you parse the string '2020/01/02' and then call the
method, you're telling moment to parse the string in the locale time, and
then convert the date to a given IANA timezone.
moment('2020/01/02', 'YYYY/MM/DD').tz('America/Los_Angeles').format('YYYYMMDD HH:mm z');
However, if you call
moment.tz() with a given IANA timezone, you're telling
moment to parse the string in the given IANA timezone, rather than in the
locale time. Notice that the below code shows the current time as exactly
midnight, rather than 21:00 ('America/Los_Angeles' is 3 hours behind New York time).
moment.tz('2020/01/02', 'YYYY/MM/DD', 'America/Los_Angeles').format('YYYYMMDD HH:mm z');
Because of this difference, you should prefer to use
moment.tz() when creating
new moment-timezone objects, rather than changing the timezone after creation
When Timezones Matter
Timezones often pop up when building apps where you have objects with an implicit location. For example, if you're building a blog, and a user posts a comment at 5pm in London, it is arguably correct to show a user looking at the comment in New York that the comment was posted at 12pm.
But suppose you're building an events platform. If an event is happening at 5pm in London and that event isn't being streamed online, a user in New York should still see 5pm. If the expectation is that, if you are participating in the event, you will be in London, then showing London time regardless of the user's current location is the correct behavior.
Moment-timezone is a great library for handling times in different timezones. Given a Unix timestamp or a date string, you can convert it to a fully fledged moment object in any IANA timezone. No need to worry about daylight savings time.