JavaScript 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 Overview
JavaScript Temporal are built-in date and time objects that are easier and safer to use than Date.
Temporal separates date and time into distinct classes to prevent "wall-clock" errors.
Why Was Temporal Created?
The Date object was created in 1995 and has some design issues that still cause bugs today.
For example, months in Date are zero-based, which is confusing.
Another problem is that many Date methods change the same object (mutation), which can create unexpected results.
Example
// Create a Date
let d = new Date(2026, 5, 17);
// Add 7 days
d.setDate(d.getDate() + 7);
// Here the original date (d) is lost
Try it Yourself »
Temporal was created to solve these issues with clearer object types and predictable behavior.
A Simple Temporal Example
With Temporal, you can get today's date and add days in a clear and safe way.
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });
Try it Yourself »
Temporal Dates are Immutable
In the example above, notice that today is not changed.
Temporal returns a new value instead of modifying the existing one.
Temporal objects are immutable, which means they cannot be changed after they are created.
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.
Temporal Object Types
Temporal includes several object types for different kinds of date and time values:
| Object | Description |
|---|---|
Temporal.Now | Current time (UTC timestamp) |
Temporal.Instant | Exact moment in time (UTC timestamp) |
Temporal.PlainDate | Plain date only (year, month, day) |
Temporal.PlainTime | Plain time without a time zone |
Temporal.PlainDateTime | Date and time without a time zone |
Temporal.ZonedDateTime | Date and time with a time zone |
Temporal.Duration | Length of time (days, hours, minutes) |
JavaScript Date vs Temporal
| Feature | Date | Temporal |
|---|---|---|
| Created | 1995 | 2026 |
| Time zone support | Limited | Built-in |
| Immutable | No | Yes |
| Date-Only Type | No | Yes |
| Time-Only Type | No | Yes |
| 1-Based Months | No | Yes |
| DST safe arithmetic | No | Yes |
| RFC 5545 iCalendar | No | Yes |
| Modern API design | No | Yes |
| Precisition | Milliseconds | Nanoseconds |
When to Use Temporal?
Use Temporal when you need reliable date and time handling.
You need correct time zone support.
You want safe date arithmetic (add or subtract days, months, years).
You want to avoid DST bugs.
You want predictable and readable code.
You may still use Date for very simple tasks, or when you must support environments where Temporal is not available.
Summary
Temporal is the modern way to work with dates and times in JavaScript.
Temporal fixes common Date problems like time zones, DST bugs, and confusing date math.
In the next chaper, you will learn about the difference between the new Temporal and the old Date.
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 | 🚫 | 🚫 |
Note
Temporal is a major update to the JavaScript standard (TC39).
It is expected to reach wide availability across browsers throughout 2026.
