JavaScript Temporal
What is JavaScript Temporal?
Temporal is the new standard for date and time in JavaScript.
New Temporal objects are designed to replace the old Date object.
Unlike legacy Date, Temporal objects are immutable and provide first-class support for time zones and non-Gregorian calendars.
Temporal separates date and time into distinct classes to prevent "wall-clock" errors.
Main Temporal Objects
Temporal objects are the core part of the Temporal API which aims to replace the old Date object.
| Object | Description |
|---|---|
| Temporal.Now | The current time |
| Temporal.ZonedDateTime | Date and time in a specific time zone |
| Temporal.Instant | A fixed point in time, independent of time zone |
All Temporal objects are immutable, which helps prevent bugs related to accidental modification of time values.
Temporal.Now
The Temporal.Now object has methods for getting the current time in various formats.
Use the Temporal.Now.zonedDateTimeISO() method for current system time:
Use the Temporal.Now.plainDateISO() method for calender date only:
Temporal.ZonedDateTime
A Temporal.ZonedDateTime is a timezone and calendar-aware
date/time object that represents a real time event from the perspective of a particular
region on Earth.
Example: December 7th, 1995 at 3:24 AM in US Pacific time (in Gregorian calendar).
Example
const zonedDate = Temporal.ZonedDateTime.from({
timeZone: 'America/Los_Angeles',
year: 1995,
month: 12,
day: 7,
hour: 3,
minute: 24,
second: 30,
millisecond: 0,
microsecond: 3,
nanosecond: 500
});
Try it Yourself »
The Temporal.ZonedDateTime object is optimized for cases that
require a time zone, DST-safe arithmetic and interoperability with an RFC 5545 calendar.
DST-Safe Arithmetic
DST-safe arithmetic ensures time calculations (addition and subtraction) remain accurate across Daylight Saving Time (DST) transitions, preventing 1-hour errors.
It involves using timezone and calendar-aware objects (ZonedDateTime) that understand local clock shifts.
RFC 5545 iCalendar
RFC 5545, titled iCalendar (Internet Calendaring and Scheduling Core Object Specification), is the industry standard for exchanging calendar and scheduling information.
It allows different systems (like Google Calendar, Apple Calendar, and Microsoft Outlook) to communicate seamlessly.
The Temporal.Instant Object
Temporal.Instant is a JavaScript object representing a
single point in time.
Temporal.Instant stores a count of nanoseconds since the Unix epoch
(midnight January 1, 1970).
Temporal.Instant has no time zone or calendar.
Note
Nanosecond precision is 1000 times higher than the millisecond precision of the old Date object.
Creating an Instant:
| From | Code |
| String | Temporal.Instant.from('1969-07-20T20:17:00Z') |
| Current time | Temporal.Now.instant() |
| Epoch millisec | Temporal.Instant.fromEpochMilliseconds() |
| Epoch nanosec | Temporal.Instant.fromEpochNanoseconds() |
Arithmetic and Comparison:
| Method | Description |
add() |
Adds a duration (hours, minutes, seconds) to an instant |
subtract() |
Subtracts duration (hours, minutes, seconds) to an instant |
compare() |
Returns -1 if the first date is earlier, 1 if later and 0 if equal |
equals() |
The Temporal.Instant.from() Method
To get human-readable components like year, month, or hour, you must explicitly convert it to a
Temporal.ZonedDateTime using a specific time zone.
Temporal PlainDate Objects
A Temporal.PlainDate object in JavaScript represents a calendar date (year, month, and day) without a specific time zone, typically in ISO 8601 format ("2026-05-01").
It is used for dates that remain the same regardless of time zone, such as birthdays or holidays:
| Object | Description |
|---|---|
| Temporal.PlainDate | Calendar date only (2026-05-21) |
| Temporal.PlainTime | Time of day only (14:30:00) |
| Temporal.PlainMonthDay | Month and day only (05-01) |
| Temporal.PlainYearMonth | Year and month only (2026-05) |
Learn More:
Temporal Arithmetic
| Method | Returns |
|---|---|
| temporal.add() | New temporal representing a date moved forward by a duration |
| temporal.subtract() | New temporal representing a date moved backward by a duration |
| temporal.since() | The duration between two temporal objects |
| temporal.until() | The duration between two temporal objects |
| temporal.with() | New temporal with fields replaced (change a day) |
Temporal Comparison
| Method | Description |
|---|---|
| Temporal.PlainDate.compare() | Static method useful for sorting arrays of dates (returns -1, 0, or 1) |
| temporal.equals() | Returns true if two dates (and their calendars) are identical |
| Temporal.Duration | The difference between two time points |
Learn More:
Browser Support
Temporal is an ES2026 feature. It is not fully supported in all browsers:
| Chrome 144 |
Edge 144 |
Firefox 139 |
Safari |
Opera |
| Jan 2026 | Jan 2026 | May 2025 | 🚫 | 🚫 |
