Learn More

Try out the world’s first micro-repo!

Learn More

A Guide to the Temporal API in JavaScript

A Guide to the Temporal API in JavaScript

Every JavaScript developer has worked with date and time at one point in their careers, so we all know that working with dates in JavaScript is very ugly. The Date API is clunky and has almost no methods that respect immutability. This pushed most of us to resort to libraries like moment.js or date-fns in a bid for a simpler way of working with time in JavaScript. Enter the Temporal API.

The Temporal API comes with the Temporal object in JavaScript and lots of methods that make working with dates and time almost pain-free. This article will take a look at the Temporal API, what issues it solves, and some data types available with it.

Some issues most developers face when using the Date object in Javascript include that it is error prone when doing string to date parsing, it only supports the Gregorian calendar, and it is easily mutable.

The Temporal API deals with most of these issues by:

  • Being an API that's easy to use for dates and times
  • Providing support for non-Gregorian calendars
  • Providing support for all timezones

Temporal API Data Types

There are two data types which the Temporal API makes available to us: The Plain data type and the Zoned data type.

Plain data type: The Plain data type represents a date or time that has no time zone information. The Plain data type is best utilized when you want to represent time with no information as to what time zone the time comes from.

Zoned data type: The Zoned data type represents a specific date and time with information to a specific time zone. Use it when dealing with specific times within certain time zones or if you need to format or perform time/date difference/addition operations that take time zone-specific information into account.

Enabling the Temporal API in your project

The first step to using the Temporal API is to install the package by running the command below:

npm install @js-temporal/polyfill

We will install Snowpack as a dev dependency to enable us to build and ship our files to the browser:

npm install --save-dev snowpack

In the package.json file, paste the code below into the scripts section.

"start": "snowpack dev"

Create an index.html file and paste the code below into the file:

<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Temporal API</title>
<script src="index.js" type="module"></script>
<h1>A guide to the Temporal API</h1>

Create an index.js file and import the Temporal package into it.

import { Temporal } from '@js-temporal/polyfill';

With that done, run npm start in your terminal to start your development server. Let’s look at some Temporal data types that you will most likely work with.


Given that it just provides a date and time without taking into account the time zone, the PlainDateTime object is one of the simplest objects to comprehend. Using Temporal.now is the simplest way to construct a new PlainDateTime.

The temporal.now() function is a method in the Temporal API that returns the current date and time in the local time zone. This function can be used to get the current time in a script or program using the Temporal API.

const todaysDateAndTime = Temporal.Now.plainDateTimeISO()
console.log(todaysDateAndTime.toString()) //2022-12-30T11:39:20.729760718

You can even go as far as getting the date and time differently and in a human readable fashion:

const onlyTheDate = Temporal.Now.plainDateISO()
const onlyTheTime = Temporal.Now.plainTimeISO()
console.log(onlyTheDate.toString()) //2022-12-30
console.log(onlyTheTime.toString()) //11:49:14.63735463


The Zoned data type represents a specific date and time with information to a specific time zone. Use it when dealing with specific times within certain time zones or needing to format or perform time/date difference/addition operations that take time zone-specific information into account. A ZonedDateTime is a datetime that includes all time zone-related data, making it the ideal choice for displaying local dates and times and doing computations involving things like daylight savings time.

Some examples of how to use the Zoned data type are shown below:

const timeInMyLocation = Temporal.Now.zonedDateTimeISO();
console.log(timeInMyLocation.toString()); //2022-12-31T11:05:26.604126592+01:00[Africa/Lagos]
const americanTime = Temporal.Now.zonedDateTimeISO("America/Los_Angeles");
console.log(americanTime.toString()); //2022-12-31T02:05:26.611126604-08:00[America/Los_Angeles]

Helper Methods in the Temporal API

The Temporal API also comes with some helper methods that make working with date and time a joy. We’ll cover some of these methods in this section.

Adding and subtracting methods

JavaScript makes it quite difficult to add or subtract portions of dates and time, but thanks to the Temporal API, all of the data types we've discussed so far have add and subtract methods built in that make the process relatively simple. The arguments for both functions are same; the only distinction is that one subtracts and the other adds. To use the add and subtract methods, we only need to pass the properties we want to change.

An example is shown below:

const today = Temporal.Now.plainDateISO()
console.log(today.subtract({ days: 12, months: 5 }).toString()) //2022-07-20

The Temporal API automatically takes care of overflow for you and clamps the date to the nearest valid date. This means that if you try to add one day to March 31st, then the date will automatically be changed to April 1st because March 32nd doesn't exist and is not valid.

The with method

The with method takes in an object of fields and uses that object to create a new instance of the current date. This new instance will bear the date but will have the properties specified in the object changed.

Let’s take a look at an example:

const today = Temporal.Now.plainDateISO()
console.log(today.with({ year: 1999, month: 5 }).toString()) //1999-05-01

In the example above, we specified that we want today's date but we want the year to be 1999 and we want the month to be the fifth month (May).

Browser Support for the Temporal API

The Temporal API is great, but, unfortunately, there is currently no browser support for it. This is because this API is still in Proposal Stage 3.

However, you can still make use of this API by using a polyfill. For this API, there are a variety of polyfills available, but I like the @js-temporal/polyfill the best. You can use the Temporal API as soon as you install this package.


This article covers the Temporal API, how it works, and solutions it gives to the problems with using the Date() object in JavaScript. For further information concerning the Temporal API, please refer to:

  1. Temporal Proposal
  2. The Temporal Documentation
  3. The Temporal Cookbook Examples

Interested in becoming a Pieces Content Partner?

Learn More

Get our latest blog posts and product updates by signing up for our monthly newsletter! 

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Table of Contents



More from Pieces