Back to Main Page

Temporal API

Limited Availability

Check the detailed baseline availability here.

This Temporal API is newly added API that is meant to replace the legacy Date object.

According to MDN documentation:

"JavaScript has had the Date object for handling date and time since its first days. However, the Date API is based on the poorly designed java.util.Date class from Java, which was replaced in the early 2010s; but, because of JavaScript's goal of backward compatibility, Date sticks around in the language.

The important lesson to preface the whole introduction is that date handling is complex. Most of the problems of Date are fixable by adding more methods, but a fundamental design flaw remains: it exposes so many methods on the same object that developers are often confused about what to use, leading to unexpected pitfalls. A well-designed API not only needs to do more, but also should do less with each level of abstraction, because preventing misuse is as important as enabling use cases.

Date objects wear two hats simultaneously:

  • As a timestamp: the number of milliseconds or nanoseconds elapsed since a fixed point in time (known as the epoch).
  • As a combination of components: year, month, day, hour, minute, second, millisecond, and nanosecond. The year, month, and day identifiers only make sense with reference to a calendar system. The whole combination maps to a unique instant in history when associated with a time zone. Date objects provide methods for reading and modifying these components.

Time zones underlie a significant number of date-related bugs. When interacting with a Date via the "combination of components" model, the time can only be in two time zones: UTC and local (device), and there's no way to specify an arbitrary time zone. Also lacking is the concept of "no time zone": this is known as a calendar date (for dates) or wall-clock time (for times), which is a time you "read off a calendar or clock". For example, if you are setting a daily wake up alarm, you will want to set it to "8:00AM" regardless of whether it is daylight saving time or not, whether you have traveled to a different time zone, etc.

A second feature lacking from Date is a calender system. Most people may be familiar with the Gregorian calendar, where there are two eras, BC and AD; there are 12 months; each month has a different number of days; there's a leap year every 4 years; and so on. However, some of these concepts may not apply when you are working with another calendar system, such as the Hebrew calendar, the Chinese calendar, the Japanese calendar, etc. With Date, you can only work with the Gregorian calendar model.

There are many other undesirable legacies about Date, such as all setters being mutating (which often causes unwanted side effects), the date time string format being impossible to parse in a consistent way, etc. In the end, the best solution is to build a new API from scratch, which is what Temporal is."

To summerize, some of the biggest shortcoming of Date include:

  • A Date object represents both a point in time (a timestamp) and individual date and time components (year, month, day, hour, etc.) making the API harder to understand and easier to misuse.
  • Date only works with UTC and the user's local time zone. This makes the API to work with arbitrary time zones or represent values that have no associated time zone such as a calendar date or wall-clock time.
  • Most setter methods modify the existing object instead of returning a new one which can introduce unexpected side effects.
  • Parsing date strings has historically been a source of bugs and not every format is interpreted consistently across environments.
  • Date is built around the Gregorian calendar and cannot be natively represent dates from other calendar systems.

These are the reasons why they decide to work on the new API as a modern replacement.

This article focuses on using the Temporal API in real-world code. It does not cover the underlying specification in depth, so if you're interested in the design decisions or technical details, refer to the official specification and the Temporal working group's documentation.

When you need to represent an exact moment in history. Temporal provides two main options.

Temporal.Instant represents a unique point on the timeline using a timestamp. 


const instant = Temporal.Instant.from("2026-07-09T12:00:00Z");
console.log(instant);

An Instant does not have a time zone or calendar. It simply represents a moment in time. When you need to associate that moment with a specific time zone, use Temporal.ZonedDateTime. 


const zonedDateTime = Temporal.ZonedDateTime.from( 
  "2026-07-09T12:00:00+09:00[Asia/Tokyo]"
);

console.log(zonedDateTime);

A ZonedDateTime combines a date, time, time zone and calendar to represent a real-world date and time.

  • Temporal.PlainDate - a calendar date
  • Temporal.PlainTime - a wall-clock time
  • Temporal.PlainDateTime - a date combined with a time

Similarly, these APIs can be used as follows:


const birthday = Temporal.PlainDate.from("1995-05-23");

const meetingTime = Temporal.PlainTime.from("09:30");

const appointment = Temporal.PlainDateTime.from(
  "2026-07-09T09:30"
);

These values do not represent a specific moment in history because they do not contain a time zone.

Tempora.Duration represents a length of time rather than a point in time. 


const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration);