JavaScript Temporal Tutorial
Temporal Study Path
Learn JavaScript Temporal in the Right Order.
- What is JavaScript Temporal?
- Temporal vs JavaScript Date
- Temporal Duration
- Temporal Instant
- Temporal PlainDateTime
- Temporal PlainDate
- Temporal PlainTime
- Temporal ZonedDateTime
- Temporal Now
- Temporal Arithmetic
- Temporal Differences
- Temporal Conversions
- Temporal Formats
- Temporal Mistakes
- How to Migrate to Temporal
What is JavaScript Temporal?
Temporal is the new standard for date and time in JavaScript.
New Temporal objects was designed to replace the old Date object.
Unlike legacy Date, Temporal objects are immutable and provide first-class support for time zones, daylight saving time, date arithmetic and non-Gregorian calendars.
Temporal vs Date
Compare JavaScript Temporal and JavaScrip Date.
Learn the differences between Date and Temporal
- Date is 0-based, Temporal is 1-based
- Date arithmetic is manual, Temporal is built-in
- Date mutates values, Temporal does not
- Date mixes UTC and time zones, Temporal separates them
- Date math can fail in DSD handling, Temporal can not
Learn why Temporal is the modern alternative to Date.
Temporal.Duration
The Temporal.Duration object represents a length of time.
Example: 7 days and 1 hour.
The Temporal.Duration object includes these properties:
years, months, weeks, days, hours, minutes, seconds, milliseconds, and nanoseconds.
The Duration object is used to perform precise date and time arithmetic (e.g. add and subtract) without the bugs and complexity associated with the old JavaScript Date object.
What You Should Learn:
- How to use JavaScript Temporal.Duration
- How to represent and calculate lengths of time
- How to add and subtract days, hours, and months more safely
Temporal.Instant
The Temporal.Instant object represents an exact moment in UTC time.
It has NO time zone and NO calendar.
It stores nanoseconds since January 1, 1970 00:00:00 (Unix epoch).
Example: 2026-05-17T14:30:00Z
What You Should Learn:
- How to work with exact moments in time
- How to compare Instants
- How to convert from timestamps
- How to replace Date.now()
Temporal.PlainDateTime
The Temporal.PlainDateTime object is a pure date and time object.
It represents a calendar date and a wall-clock time with no time zone.
Example: 2026-05-07T14:30:00.
What You Should Learn:
- How to use JavaScript Temporal.PlainDateTime
- How to work with date and time without a time zone
- How to add and subtract dates
- How to compare dates safely
Temporal.PlainDate
The Temporal.PlainDate object represents a calendar date without a time.
A Temporal.PlainDate is typically in ISO 8601 format ("2026-05-01").
It is easier to use and safer to compare than DateTime objects for dates that are the same regardless of time zone, such as birthdays or holidays.
What You Will Learn:
- How to use JavaScript Temporal.PlainDate
- How to work with dates without time
- How to add and subtract days
- How to compare dates safely
Temporal.PlainTime
The Temporal.PlainTime object is a time object without a date.
It represents an ISO 8601 wall-clock time without a date or time zone.
Example: 10:30:00.
It is useful for opening hours, alarms, and any time-only values.
Temporal.ZonedDateTime
The Temporal.ZonedDateTime object represents a date and time with a time zone.
It is the safest way to handle international date and time calculations.
It prevents common DST bugs and makes time zone conversions clear and predictable.
What You Will Learn:
- How to use JavaScript Temporal.ZonedDateTime
- How to handle time zones correctly
- How to add and subtract date
- How to avoid DST (Daylight Saving Time) bugs
- How to convert between time zones safely
Temporal.Now
The Temporal.Now object provides 5 methods to get the system's date and time.
One method for each date object:
- Temporal.Now.instant()
- Temporal.Now.plainDateISO()
- Temporal.Now.plainTimeISO()
- Temporal.Now.plainDateTimeISO()
- Temporal.Now.zonedDateTimeISO()
And one method to get system's time zone:
- Temporal.Now.timeZoneId()
Temporal Arithmetic
Temporal provides methods for easy and reliable date and time arithmetic.
Add and subtract days, months, years, and time without modifying the original.
Perform date arithmetic without DST bugs and Time Zone problems.
Temporal Since / Until
Calculate Temporal Differences
You calculate the differnce between two temporal dates using
since() or until().
The since() method is the inverse of the
until() method.
The until() method is the inverse of the
since() method.
Temporal Conversion Rules
The table below shows how Temporal types can be converted.
| From | Plain Date |
Plain Time |
Plain DateTime |
Zoned DateTime |
Instant |
| PlainDate | No | Yes | No | No | |
| PlainTime | No | No | No | No | |
| PlainDateTime | Yes | Yes | Yes | No | |
| ZonedDateTime | Yes | Yes | Yes | Yes | |
| Instant | No | No | No | Yes |
Temporal Formats
Temporal dates can be serialized as strings in different ways:
| Name | Description |
|---|---|
| ISO 8601 | International standard |
| RFC 3339 | Internet standard |
| RFC 9557 | Temporal standard |
| toString() | JavaScript method |
| toLocaleString() | JavaScript method |
| Intl.DateTimeFormat() | JavaScript method |
Browser Support
Temporal is a major update to the JavaScript standard (TC39).
It is currently fully supported in Chrome, Edge, and Firefox, and is expected to reach full availability across browsers before the summer of 2026.
| Chrome 144 |
Edge 144 |
Firefox 139 |
Safari |
Opera |
| Jan 2026 | Jan 2026 | May 2025 | 🚫 | 🚫 |
Opera and Safari Support
Opera support will probably appear 1-3 browser cycles after Chromium, which often means a few months later.
The Safari implementation is in development and can be tested today in Safari Technology Preview by enabling the --use-temporal runtime flag.
Polyfill
Until Opera and Safari supports Temporal natively, you can use the official polyfill:
<script
src="https://cdn.jsdelivr.net/npm/@js-temporal/polyfill/dist/index.umd.js">
</script>
