Skip to content
Tutorials Center
My learning

Topics

Lesson 112 of 156 ยท Built-in Tools

The Temporal API

Learn the modern Temporal API for dates and times in JavaScript - plain dates, zoned times, instants, durations, math, comparison and support status.

In Dates and Times you met the Date object and its quirks: months that start at zero, objects that change under your feet, and a time zone model that only knows "UTC" and "wherever this computer is". Temporal is the built-in replacement, designed over several years to fix all of that.

Temporal is not one class but a small family of types. Each one answers a precise question: "which calendar day?", "what time on the clock?", "which exact moment?", "how long?". Picking the right type up front makes whole categories of bugs impossible. In this lesson you'll meet each type, do date math, compare values, and work across time zones.

Support status (late 2026): Temporal shipped in Firefox in 2025 and in Chrome and Edge in early 2026. Safari support was still in progress at the time of writing, and older browsers and older Node.js versions don't have it. Every example below starts with a feature check, so it runs everywhere โ€” if your browser lacks Temporal, you'll see a message instead of a crash. In production, feature-detect and load the official polyfill (@js-temporal/polyfill or temporal-polyfill) where it's missing.

Feature detection first

Temporal is a global namespace object, like Math or Intl. You never write new Temporal(); you use the classes inside it, such as Temporal.PlainDate. Checking for support is one line:

JavaScript
const hasTemporal = typeof Temporal !== "undefined";

Use typeof rather than if (Temporal): reading an undeclared variable throws a ReferenceError, while typeof safely returns "undefined".

The Temporal family

Here are the types you'll use most, and the question each one answers:

Type Holds Example Use it for
Temporal.PlainDate a calendar date 2026-03-15 birthdays, due dates, holidays
Temporal.PlainTime a wall-clock time 09:30 opening hours, alarm times
Temporal.PlainDateTime date + time, no zone 2026-03-15T09:30 a form's local input before you know the zone
Temporal.ZonedDateTime date + time + time zone 2026-03-15T09:30+01:00[Europe/Paris] meetings, flights, anything that happens somewhere
Temporal.Instant an exact moment, no zone 2026-03-15T08:30:00Z log timestamps, database values
Temporal.Duration a length of time P1DT2H (1 day, 2 hours) "in 3 weeks", timers, differences

"Plain" means no time zone attached. A PlainDate of March 15 is March 15 on every computer in the world โ€” exactly what you want for a birthday, and exactly what Date can't express.

Temporal.Now gives you the current moment in whichever shape you need: Temporal.Now.plainDateISO(), Temporal.Now.plainTimeISO(), Temporal.Now.zonedDateTimeISO(), Temporal.Now.instant() and Temporal.Now.timeZoneId().

Creating plain dates and times

There are three ways to create a Temporal value: from an ISO string, from an object of fields, or with the constructor. Notice that months are 1โ€“12, like on a real calendar.

JS PlainDate and PlainTime

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The properties are plain and readable: year, month, day, dayOfWeek, dayOfYear, daysInMonth, inLeapYear, and for times hour, minute, second, millisecond. No more getDate() versus getDay() confusion.

Invalid input throws a RangeError instead of quietly producing "Invalid Date". Temporal.PlainDate.from("2026-02-30") fails loudly, which is what you want when parsing data.

Immutable arithmetic

Every Temporal object is immutable. Methods like add(), subtract() and with() return a brand-new value and leave the original untouched. You can pass a date around without worrying that some other function will change it.

  • add({ days: 10 }) and subtract({ months: 1 }) take a duration-like object.
  • with({ day: 1 }) replaces specific fields โ€” perfect for "first day of this month".
  • Month math clamps by default: January 31 plus one month is February 28 (or 29), not March 3.
JS Date math without surprises

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Differences with until() and since()

To measure the gap between two values, call a.until(b) (from a forward to b) or b.since(a) (the same gap, seen from b). Both return a Temporal.Duration. You choose the biggest unit you want in the answer with largestUnit:

JavaScript
const start = Temporal.PlainDate.from("2026-01-15");
const end = Temporal.PlainDate.from("2026-10-14");

start.until(end).days;                                // 272
start.until(end, { largestUnit: "months" }).toString(); // "P8M29D" โ€” 8 months, 29 days

Durations

A Temporal.Duration stores amounts of each unit: years, months, weeks, days, hours, minutes, seconds and smaller. Its string form follows ISO 8601: P starts the duration, T separates the date part from the time part. So PT1H30M means 1 hour 30 minutes, and P2W means two weeks.

Durations are not "balanced" automatically. { minutes: 90 } stays 90 minutes until you ask for something else with round(), and total() converts the whole thing to one unit:

JS Working with durations

Press Run (or Ctrl + Enter) to see the console output here.

No output.

That last example shows a subtle point. "Two months" isn't a fixed number of days, so total() needs a relativeTo date to know which months you mean. Temporal refuses to guess, which is exactly the kind of honesty Date never had.

Comparing values

Don't compare Temporal objects with <, > or ===:

  • === checks whether two variables point to the same object, not whether they hold the same date.
  • < and > throw a TypeError on purpose. Temporal objects block conversion to a number, because silently comparing a date with a time would be a bug.

Use equals() for equality and the static compare() method for ordering. compare(a, b) returns -1, 0 or 1, which is exactly the shape that sort() expects:

JavaScript
const dates = ["2026-05-01", "2025-12-24", "2026-01-15"].map((s) => Temporal.PlainDate.from(s));

dates.sort(Temporal.PlainDate.compare);
// [2025-12-24, 2026-01-15, 2026-05-01]

dates[0].equals(Temporal.PlainDate.from("2025-12-24")); // true

Time zones with ZonedDateTime

A ZonedDateTime knows its exact moment and the named time zone it's displayed in (an IANA name like "America/New_York" or "Asia/Tokyo"). That's what lets it do things Date cannot: show the same moment in another city, and do math that respects daylight saving time (DST).

Watch the difference between adding one day and adding 24 hours across a DST change. In most of Europe, clocks jumped forward one hour on March 29, 2026, so that day only had 23 hours:

JS Time zones and daylight saving time

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Days are calendar days, hours are exact hours. A daily reminder should use { days: 1 } so it stays at 9:00 on the clock; a 24-hour token expiry should use { hours: 24 }.

Instants and talking to Date

A Temporal.Instant is a single point on the global timeline, with no zone and no calendar. It's the Temporal version of a Date timestamp, and it's the right type to store in a database or send over an API. Convert to a zoned value only when you need to show it to a person.

You'll still meet Date and plain numbers in existing code and APIs. Temporal converts both ways:

JavaScript
// Date or milliseconds โ†’ Instant
const instant = Temporal.Instant.fromEpochMilliseconds(Date.now());
const fromDate = new Date().toTemporalInstant();

// Instant โ†’ milliseconds โ†’ Date
const legacy = new Date(instant.epochMilliseconds);

// Instant โ†’ a person's local view
instant.toZonedDateTimeISO("Europe/Lisbon").toPlainDate().toString();

Formatting

Temporal's toString() always gives ISO 8601, which is ideal for storage and for <input type="date"> values. For people, use toLocaleString(), which goes through Intl.DateTimeFormat under the hood:

JavaScript
const date = Temporal.PlainDate.from("2026-03-15");
date.toLocaleString("en-US", { dateStyle: "full" }); // "Sunday, March 15, 2026"
date.toLocaleString("de-DE", { dateStyle: "long" }); // "15. Mรคrz 2026"

The next lesson covers locale-aware formatting in depth.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which Temporal type fits a user's birthday best?

    A birthday is a calendar date with no time or time zone. PlainDate stores exactly that, so it never shifts when viewed from another zone.
  2. 2. What does Temporal.PlainDate.from("2026-01-31").add({ months: 1 }) return?

    By default Temporal clamps to the last day of the month. Pass { overflow: "reject" } if you want an error instead.
  3. 3. How should you sort an array of PlainDate values?

    Temporal objects refuse numeric conversion, so - and < throw. The static compare() returns -1, 0 or 1, which is what sort() needs.
  4. 4. Across a spring-forward DST change, how do add({ days: 1 }) and add({ hours: 24 }) differ on a ZonedDateTime?

    Calendar units follow the wall clock in the time zone. Exact units like hours count real elapsed time, so on a 23-hour day the clock reads one hour later.
  5. 5. Why does the feature check use typeof Temporal === "undefined" instead of if (!Temporal)?

    In browsers without Temporal, the name doesn't exist at all. typeof is the one operator that can look at an undeclared name without throwing.

Summary

  • Temporal replaces Date with immutable, clearly named types: PlainDate, PlainTime, PlainDateTime, ZonedDateTime, Instant and Duration.
  • Months are 1โ€“12, invalid input throws a RangeError, and month math clamps unless you ask it to reject.
  • add(), subtract() and with() return new values; until() and since() return durations.
  • Compare with equals() and Type.compare(); <, > and === don't work on Temporal values.
  • ZonedDateTime handles named time zones and DST: calendar units follow the wall clock, exact units follow elapsed time.
  • Store Instants, display zoned values, and always feature-detect โ€” support is new and not yet universal.

Next: Formatting with Intl โ€” show numbers, currencies, dates and lists the way each user expects.