JavaScript Temporal vs 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 can fail in DSD handling, Temporal ca not
Learn why Temporal is the modern alternative to Date.,
JavaScript Date Problems
The JavaScript Date object is old and has several design problems.
These are the most common mistakes developers make when using Date objects:
Using the wrong month number because months start at 0.
Accidentally changing a date object by calling a mutating method.
Parsing unclear strings that behave differently across environments.
Mixing local time and UTC values in the same program.
Doing math across DST changes and getting unexpected hours.
The JavaScript Date object has been used since 1995.
Temporal is the modern replacement designed to fix many of Date's problems.
Date Months are 0-Based
In the JavaScript Date object, January is month 0 and December is month 11.
The Date object is confusing because most people expect January to be month 1.
Temporal Months are 1-Based
In the JavaScript Temporal object, January is month 1 and December is month 12.
This is much more user friendly.
Date Objects are Mutable
JavaScript Date objects can change.
Date objects are mutable.
Date Example
Date methods can change the original date object:
// Create a Date
let date = new Date("2026-05-17");
// Add 7 days to date
date.setDate(date.getDate() + 7);
// Here the original date is lost
Try it Yourself »
Date Example
Date methods can change other date objects:
// Create a Date
let date1 = new Date("2026-05-17");
// Create a copy
let date2 = date1;
// Add 7 days to date1
date1.setDate(date1.getDate() + 7);
// Here date2 has changed
Try it Yourself »
In the example above, the variables date1 and date2 point to the same object.
So date2 changes when date1 changes.
This can create unexpected results when date values are copied or reused.
Temporal Objects are Immutable
JavaScript Temporal objects cannot change.
Temporal objects are immutable.
Temporal Example
Temporal operations always return a new object (or value).
// Create a Date
let date1 = Temporal.PlainDate.from("2026-05-17");
// Add 7 days
let date2 = date1.add({ days: 7 });
// Here original date1 is kept
Try it Yourself »
Date Parsing is Inconsistent
A string like 2026-05-07 parses as an UTC instant in JavaScript.
JavaScript has been a minefield of different formats, browser quirks and locale surprises.
Date strings can be parsed differently across browsers and environments, and different formats may be interpreted as local time or UTC.
Date Example
const d1 = new Date("2026-05-17");
const d2 = new Date("2026-05-17T00:00:00");
const d3 = new Date("05/17/2026");
const d4 = new Date("May 17 2026");
const d5 = new Date("17 May 2026");
const d6 = new Date(2026, 4, 17);
Try it Yourself »
Temporal PlainDate
Temporal avoids the problems above by defining strict parsing rules for ISO strings.
Temporal.PlainDate is not a timestamp.
It is just 2026-05-17 with no time and no time zone.
It is safer to avoid unclear formats and use explicit formats when possible.
Date and Time Zone
new Date(2026, 4, 1) creates a timestamp of
your local time at midnight.
This means a day can "shift" when you format it to UTC.
Date Example
// Create a Date object
const date = new Date(2026, 4, 1);
// Might be another day in some time zones:
date.toISOString();
Try it Yourself »
Date Mixes Local Time and UTC
A Date object always stores a timestamp, but it can display values as local time or UTC.
This mix can easily cause confusion when converting and comparing dates.
The same moment can look different depending on how it is displayed.
Date Example
let date = new Date();
let time1 = date.toString();
let time2 = date.toUTCString();
Try it Yourself »
Temporal Separates Time and UTC
Temporal uses clear types for time zones.
Temporal.ZonedDateTime always includes a time zone.
Temporal Example
const instant = Temporal.Now.instant();
const local = Temporal.Now.zonedDateTimeISO();
Try it Yourself »
DST Can Break Date Math
Daylight saving time (DST) can cause a day to be 23 or 25 hours long.
This can break calculations that assume every day is exactly 24 hours.
Example
let start = new Date("2026-03-29T00:00:00");
let end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
The result can be off by one hour in time zones with DST changes.
Date Math
Date math often requires manual calculations.
Date Example
const start = new Date("2026-05-01");
const end = new Date("2026-05-17");
const diff = end - start;
Try it Yourself »
Temporal has built-in date arithmetic.
Temporal Example
let start = Temporal.PlainDate.from("2026-05-01");
let end = Temporal.PlainDate.from("2026-05-17");
const diff = start.until(end);
Try it Yourself »
Nanosecond Precision
The Date object uses milliseconds precision.
Temporal offers 1 million times higher nanosecond precision.
Date Mixes Everything
Date mixes everything in one object.
Date (Problem)
const date = new Date(); // date + time + zone
Temporal Uses Clear Types
Temporal objects separates different use cases into different objects.
This makes code easier to read and less error-prone.
| Object | Description |
|---|---|
| Temporal.Duration | Length of time (days, hours, minutes) |
| Temporal.Instant | Exact moment in UTC time |
| Temporal.PlainDateTime | Plain date and time (no time zone) |
| Temporal.PlainDate | Plain date only (year, month, day) |
| Temporal.PlainTime | Plain time only |
| Temporal.PlainYearMonth | Plain year and month only |
| Temporal.PlainMonthDay | Plain month and day only |
| Temporal.ZonedDateTime | Date and time with a time zone |
| Temporal.Now | Current time (UTC timestamp) |
Differences Between Date and 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 |
You may still use JavaScript Date for simple tasks such as getting a quick timestamp.
You may also need it if you support older environments without Temporal.
JavaScript Temporal is safer, clearer, and designed for modern applications.
When to Use Temporal?
You need correct time zone handling.
You work with international users.
You want safe date arithmetic.
You want clear and modern code.
