Why does JavaScript need Temporal when it already has Date?

Date has well-known flaws: it is mutable, it only models a single instant yet exposes confusing local-vs-UTC accessors, months are zero-indexed, parsing is inconsistent across engines, and it has no real time-zone or calendar support. Temporal replaces it with immutable, purpose-specific, clearly-named types and reliable ISO 8601 parsing.

What is the difference between Instant and ZonedDateTime?

Temporal.Instant is an exact point on the global timeline (like a UTC timestamp) with no time zone or calendar attached. Temporal.ZonedDateTime is that same instant interpreted in a specific time zone and calendar, so it knows the local wall-clock time, the UTC offset, and how to handle DST transitions.

When should I use PlainDate versus PlainDateTime?

Use Temporal.PlainDate for a calendar date with no time or zone, like a birthday or invoice date. Use Temporal.PlainDateTime when you also need a wall-clock time but still no time zone, such as '2026-06-06 09:00' in an unspecified location. Add a time zone only when you need ZonedDateTime.

How does Temporal handle daylight saving time?

ZonedDateTime is DST-aware. Adding 'one day' across a spring-forward boundary yields the same wall-clock time the next day even though only 23 hours elapsed, whereas adding a Duration of 24 hours adds exactly 24 hours of real time. The disambiguation option controls what happens for skipped or repeated local times.

Are Temporal objects mutable?

No. Every Temporal type is immutable. Methods like add, subtract, with and round return a brand-new object rather than changing the original, which eliminates a whole class of aliasing bugs that plagued the mutable Date object.

JavaScript Temporal API Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Temporal is the TC39 proposal that replaces the flawed Date object with a family of immutable, purpose-built date and time types. This reference lists each type, what it models, and its key methods.

How it works

Instead of one overloaded Date, Temporal gives you a type per concept:

Temporal.Now.plainDateISO();                 // today's date, no time/zone
Temporal.PlainDate.from("2026-06-06");       // a calendar date
Temporal.ZonedDateTime.from("2026-06-06T09:00[Europe/London]");
Temporal.Duration.from({ hours: 2, minutes: 30 });

The core split is wall-clock vs exact time:

PlainDate, PlainTime, PlainDateTime, PlainYearMonth, PlainMonthDay carry no time zone — they are “what a clock or calendar on the wall reads”.
Instant is an exact point on the global timeline (a UTC timestamp), with no local interpretation.
ZonedDateTime ties an instant to a time zone + calendar, so it knows local time, offset and DST rules.

Duration represents a length of time and is what until, since, add and subtract produce or consume. Every type is immutable — add/with/round return new objects.

Tips and notes

Months are 1-indexed in Temporal (January is 1), fixing the classic Date footgun.
Adding { days: 1 } to a ZonedDateTime keeps the same wall time across DST (may be 23 or 25 hours); adding { hours: 24 } always adds 24 real hours.
Use compare(a, b) static methods to sort; the ==/< operators do not work on objects.
Convert between types with methods like .toZonedDateTime(tz), .toInstant(), .toPlainDate().