Skip to main content

Date and Time Management with the Temporal API

Posted on

  • #calendar
  • #date
  • #javascript
  • #temporal
  • #time
  • #web

Are you fed up with the Date object in JavaScript? Me too! Lucky for us, the Temporal API is just around the corner. This new namespace comprises several classes for date and time management, including built-in time zone and calendar representation.

A woman rests her arms on a table, looking at the big alarm clock next to her. Photo: © KoolShooters / pexels.com

The new API is already available in Firefox Nightly. We'll quickly cover the main features of Temporal and then look at some code snippets I've compiled.

High-Level Overview

The Temporal API exposes over 200 utility methods via several classes. That's a lot! So I won't cover all of them but just name the most important features.

There are several objects for working with plain dates and times, without a time zone:

  • Temporal.PlainDate represents a calendar date without a time or time zone. Example: 2025-04-14
  • Temporal.PlainTime represents a time without a date or time zone. Example: 21:10:30.025
  • Temporal.PlainDateTime represents a date and time without a time zone. Example: 2025-04-14T21:10:30.025

To represent a unique point in time we use the Temporal.Instant object. It is semantically the same as Date, but more precise (nanosecond precision).

At last we arrive at the Temporal.ZonedDateTime object, which combines an instant, a time zone, and a calendar system. Example: 2025-04-16T21:22:26.384+02:00[Europe/Vienna].

Furthermore, we can get the current time in various formats using the Temporal.Now object. And the Temporal.Duration represents a difference between two time points, which can also be used in date/time calculations.

Code Snippets

I've compiled a list of code snippets for working with the new Temporal API in JavaScript. Here's a few examples:

Create a new plain date object and access parts of it

let calendarDate = Temporal.PlainDate.from("2025-04-09"); calendarDate.day; // 9 calendarDate.dayOfWeek; // 3 calendarDate.month; // 4 calendarDate.year; // 2025

Add a duration to an immutable plain time object

let t1 = new Temporal.PlainTime(14, 55, 10, 250); // "14:55:10.25" let t2 = t1.add({ seconds: 5000 }); t2.toString(); // "16:18:30.25"

Language-sensitive formatting of a zoned datetime

let datetime = Temporal.ZonedDateTime.from("2020-10-15T08:30Z[America/New_York]"); datetime.toLocaleString("en-US"); // "10/15/2020, 4:30:00 AM EDT"

Compare two instants

let inst1 = Temporal.Instant.from("2022-07-10T12:00Z"); let inst2 = Temporal.Instant.from("2023-01-01T15+01:00"); inst1.equals(inst2); // false Temporal.Instant.compare(inst1, inst2); // -1 (is before)

Round a duration to a specified unit

let duration = Temporal.PlainTime.from("12:30").until("17:45"); // "PT5H15M" duration = duration.round("hours"); // "PT5H"

Browser Support

Are you hyped already? I sure am! And it gets even better: Firefox will soon be the first browser to ship Temporal in stable release. Firefox 139 is due on May 27.

The implementation in other browsers is still a work in progress (Chromium, WebKit/Safari). But I'm sure they'll get there soon. In the meantime: Get familiar with Temporal in Firefox Nightly. 😉

Posted on

HomepageTop