Temporal API Time Zones: Convert Times
Tags: javascript, webdev
Published: 2022-05-18 14:03:34

---
title: "Temporal API Time Zones: Convert Times"
published: "true"
description: "Temporal API time zones: how you can use the new JavaScript Temporal API to convert a time instant from one time zone to another."
tags: "javascript, webdev"
canonical_url: "https://rodneylab.com/temporal-api-time-zones/"
cover_image: "https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ybjwdk0qel01xz66bffc.png"
---


## 🌍 Temporal API Time Zones

In this post on the Temporal API Time Zone we first get a quick introduction to the new JavaScript API before, exploring one of its most powerful features: handling time zones.  Brandon Eich was in a race against the clock when he first wrote JavaScript back in 1995.  Time pressure resulted in basing JavaScript&rsquo;s Time object on a now deprecated Java API.  Until now, little has been done to improve on the original JavaScript time object and methods. One major issue is handling time zones.  The Temporal API has your back here. It is still a proposal and not recommended for production use. That said, you can try it in side projects using a polyfill, with little effort. Once it is integrated into ECMAScript, it will be a sight for sore eyes!

We will take a quick look at setting up the polyfill then see how you can use the Temporal API time zones.  An example use case is to convert a meeting time from your local time zone for a colleague on another continent.  No need to guess daylight saving adjustments any more!

## ⏪ Temporal API Time Zones: Polyfill

There are <a aria-label="See full list of Temporal Polyfills" href="https://github.com/tc39/proposal-temporal#polyfills">a couple of polyfills suggested by TC39 for the Temporal API</a>.  We just take the first one here.  Polyfills let you write code using new APIs before the APIs are widely supported.  Behind the scenes, they convert your code (written using the new API) to widely supported code.  This lets you get an early start on the the new API.

To get going install the polyfill package in your project:

```shell
pnpm add @js-temporal/polyfill
```

Then import it in any JavaScript or TypeScript source files in which you want to use Temporal:

```javascript
import {Temporal} from '@js-temporal/polyfill'
 
const now = Temporal.Now.plainDateTimeISO();
```

That&rsquo;s it.  Next we see how you can do time conversion.


## 🕰 Temporal API Time Zones: Convert between Zones

Let&rsquo;s take a concrete use case.  We are in London and have a friend in São Paulo.  We want to call them now, but want to make sure it is a socially acceptable time for the call in São Paulo before dialling.  

![Temporal API Time Zones: Screenshot: image shows time at 18:00 for the Europe/London time zone and 14:00 for America/Sao Paulo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y4uxho6edi0n2n6er1xw.png)

Lets start by setting up the local time zone.  The Temporal API supports Time Zones using common time zone abbreviations (like CET for Central European Time, <a aria-label="Open t z dat time zone information" href="https://data.iana.org/time-zones/theory.html">see IANA docs for more colour</a>) as well as city based ones.  We will go for the latter:

```javascript
const localTimeZoneName = 'Europe/London';
const localDateTime = Temporal.Now.plainDateTimeISO()
  .toZonedDateTime(localTimeZoneName);
```

`Temporal.Now.plainDateTimeISO()` gives us the current time.  Because we know we will be doing time zone conversion on it, we can use the `toZonedDateTime` method to attach the local time zone to it.  This is an exact point in time, meaning although it is the clock time in London, it will not be the clock time in Berlin or Los Angeles.

### Conversion

Next we can set up our friend&rsquo;s time zone:

```javascript
const remoteTimeZoneName = 'America/Sao_Paulo';
const remoteTimeZone = Temporal.TimeZone
  .from(remoteTimeZoneName);
```

this gives us a Time Zone object, for São Paulo, which we can use to translate time instants into São Paulo time:

```javascript
const remoteDateTime = localDateTime
  .withTimeZone(remoteTimeZone);
```

Finally, you might want this in a human-readable format.  You probably already know the date/month order is reversed in some countries and can be a source of confusion.  We can output our human readable date using the `medium` or `long` style, which output text instead of numbers for months to help avoid a misunderstanding:

```javascript
console.log(remoteDateTime
  .toLocaleString('en-GB',
    {
      dateStyle: 'medium',
      timeStyle: 'short'
    },
  )
);
```

This outputs something like:

```plaintext
11 May 2022, 14:00
```

You can read more about Temporal API time zones in the <a aria-label="OPen T C 39 docs on Temporal Time Zone" href="https://tc39.es/proposal-temporal/docs/timezone.html">TC39 Temporal.TimeZone docs</a> and <a aria-label="Open docs on Time conversion in temporal cookbook" href="https://tc39.es/proposal-temporal/docs/cookbook.html#time-zone-conversion">Temporal Cookbook section on time zone conversion</a>.  I am also collating a list of methods which I find useful into a cheatsheet.  We&rsquo;ll have a quick look at that and then wrap up.  Before that though, you can <a aria-label="Open up the code in Stack Blitz"  href="https://stackblitz.com/github/rodneylab/astro/tree/main/demos/temporal-api-time-zones">open up the code used to generate the example in StackBlitz</a> if you want to play around.  It is just an Astro file.  You will see the JavaScript code for the time conversion at the top of the `src/pages/index.astro`&nbsp;file.

## 🐘 Temporal API Cheatsheet

<a href="https://temporal-api-cheatsheet.rodneylab.com/" aria-label="Open the Temporal A P I site" >
![Temporal API Cheatsheet: Site: screenshot show close-up on polyfill section of the site and includes details of how to install and import the polyfill for the Temporal A P I](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/uvo5cf2kybmhvuudxs8a.png)</a>

The <a aria-label="Read article on the Temporal A P I cheatsheet" href="https://rodneylab.com/temporal-api-cheatsheet/">Temporal API Cheatsheet</a> is a quick reference learn in public list of Temporal methods.  I am adding new methods to it as I discover more about the new API.  It is open source and you can <a aria-label="Open a pull request on the Temporal API Cheatsheet" href="https://github.com/rodneylab/temporal-api-cheatsheet/pulls">add to it yourself</a>.

## 🙌🏽 Temporal API Time Zones: Wrapping Up

In this article, we have had a quick look at the Temporal API time zones functionality.  In particular, we saw:

- how to create an exact time as a zoned date time in the Temporal API,
- a way to convert an instant from one time zone to another, like you would need to communicate an online meeting time to participants in different locations,
- how to output a date time in human readable format avoiding potential confusion from differing international conventions on month / date order.

You can see the code for the demo in the <a aria-label="Open the demo code in the Rodney Lab Git Hub Repo" href="https://github.com/rodneylab/astro/tree/main/demos/temporal-api-time-zones">Rodney Lab GitHub repo</a>.

I hope you found this article useful and am keen to hear how you will the starter on your own projects as well as possible improvements.

## 🙏🏽 Temporal API Cheatsheet: Feedback

Have you found the post useful? Would you prefer to see posts on another topic instead? Get in touch with ideas for new posts. Also if you like my writing style, get in touch if I can write some posts for your company site on a consultancy basis. Read on to find ways to get in touch, further below. If you want to support posts similar to this one and can spare a few dollars, euros or pounds, please <a aria-label="Support Rodney Lab via Buy me a Coffee" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875/giving/">consider supporting me through Buy me a Coffee</a>.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via <a href="https://twitter.com/messages/compose?recipient_id=1323579817258831875" aria-label="Reach out on Twitter">@askRodney</a> on Twitter and also <a aria-label="Contact Rodney Lab via Telegram" href="https://t.me/askRodney">askRodney on Telegram</a>. Also, see <a aria-label="Get in touch with Rodney Lab" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875/contact">further ways to get in touch with Rodney Lab</a>. I post regularly on <a aria-label="See posts on Astro" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875/tags/astro/">Astro</a> as well as <a aria-label="See posts on svelte kit" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875/tags/sveltekit/">SvelteKit</a>. Also <a aria-label="Subscribe to the Rodney Lab newsletter" href="https://twitter.com/messages/compose?recipient_id=1323579817258831875/about/#newsletter">subscribe to the newsletter to keep up-to-date</a> with our latest projects.