Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Date and Intl

The Temporal API

Overview of the JavaScript Temporal API: PlainDate, ZonedDateTime, Instant and Duration, immutable date math and time zones, plus how to check support.

Temporal is a built-in namespace object for working with dates, times, time zones and durations. It was designed to replace the old Date object, which mixes an instant in time with local-time getters, mutates in place, counts months from zero and parses strings inconsistently.

Instead of one type, Temporal has several, each for a specific job: a calendar date with no time, a wall-clock time with no date, an exact moment, a moment in a named time zone, and a length of time. All of them are immutable: methods like add() return a new object.

This is a concept page: it explains the family of types and how they fit together. Temporal is recent, so check a compatibility table, and test for it before use.

JavaScript
if (typeof Temporal === "undefined") {
  console.log("Temporal is not available here.");
} else {
  console.log(Temporal.PlainDate.from("2026-03-15").add({ days: 20 }).toString());
}

Try it

JS Plain dates and durations

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Instants and time zones

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The family of types

Type What it represents
Temporal.PlainDate A calendar date with no time or zone, such as a birthday.
Temporal.PlainTime A wall-clock time with no date, such as "opens at 09:00".
Temporal.PlainDateTime A date and a time with no zone.
Temporal.PlainYearMonth, Temporal.PlainMonthDay A month of a year (a billing month) or a day of a year (a recurring holiday).
Temporal.Instant One exact moment in time, with nanosecond precision and no zone.
Temporal.ZonedDateTime An exact moment seen in a named time zone, with the correct offset.
Temporal.Duration A length of time such as one hour and thirty minutes.
Temporal.Now Functions that give the current instant, date or zone: Temporal.Now.instant(), Temporal.Now.plainDateISO(), Temporal.Now.timeZoneId().

Choosing a type

  • Use PlainDate when the zone is irrelevant, such as a birthday or a deadline "by the 15th".
  • Use Instant for timestamps you store and compare: log entries, events that happened.
  • Use ZonedDateTime when humans need local clock time in a place, such as a future meeting. It keeps the zone, so daylight-saving rules are applied for you.
  • Use Duration for amounts of time and for the result of until() and since().

Usage notes

  • Immutable. add(), subtract(), with() and round() return new objects; the original never changes.
  • Months are 1 to 12 and weekdays are 1 (Monday) to 7 (Sunday), unlike Date.
  • Invalid strings throw. Temporal.PlainDate.from("2026-02-30") throws a RangeError. With an object such as { year: 2026, month: 2, day: 30 } the default is to clamp to the last valid day; pass { overflow: "reject" } to throw instead.
  • Calendar units need a calendar date. Adding hours to a PlainDate throws, because it has no time.
  • Compare with compare() and equals(). Comparing objects with < or > throws, because valueOf() is deliberately blocked. This avoids silent mistakes.
  • Days are not always 24 hours in a zone. add({ days: 1 }) keeps the wall-clock time, while add({ hours: 24 }) adds elapsed time.
  • Convert from Date with date.toTemporalInstant() where available, or from date.getTime() with Temporal.Instant.fromEpochMilliseconds().
  • Formatting: toString() gives ISO-style text, and toLocaleString() uses Intl.DateTimeFormat rules.

Browser support

Temporal is new. It is available in some current browsers and runtimes and still missing in others, so check a compatibility table and feature-detect with typeof Temporal. For older environments you would need a polyfill or the Date object.