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.
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
Press Run (or Ctrl + Enter) to see the console output here.
No output.
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
PlainDatewhen the zone is irrelevant, such as a birthday or a deadline "by the 15th". - Use
Instantfor timestamps you store and compare: log entries, events that happened. - Use
ZonedDateTimewhen 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
Durationfor amounts of time and for the result ofuntil()andsince().
Usage notes
- Immutable.
add(),subtract(),with()andround()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 aRangeError. 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
PlainDatethrows, because it has no time. - Compare with
compare()andequals(). Comparing objects with<or>throws, becausevalueOf()is deliberately blocked. This avoids silent mistakes. - Days are not always 24 hours in a zone.
add({ days: 1 })keeps the wall-clock time, whileadd({ hours: 24 })adds elapsed time. - Convert from
Datewithdate.toTemporalInstant()where available, or fromdate.getTime()withTemporal.Instant.fromEpochMilliseconds(). - Formatting:
toString()gives ISO-style text, andtoLocaleString()usesIntl.DateTimeFormatrules.
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.