Platform under construction

Dates, Time & Intl

Intermediate

Temporal

Temporal is the modern JavaScript date and time API. It separates instants, plain dates, wall-clock times and zoned date-times.

if ("Temporal" in globalThis) {
  const date = Temporal.PlainDate.from("2026-01-01");
  console.log(date.add({ days: 7 }).toString());
}

Dates, Time & Intl

Temporal fixes the biggest Date design problems by using clearer types.

Temporal is designed as a modern replacement for Date. It has separate types for different date-time concepts instead of forcing everything into one mutable Date object.

Temporal.PlainDate represents a calendar date without a time zone. Temporal.Instant represents an exact instant. Temporal.ZonedDateTime represents an instant with a time zone and calendar context.

Temporal is powerful, but not yet something to assume in every browser without checking support. Use feature detection and consider a polyfill where production support requires it.

PlainDate

A calendar date without time or time zone.

PlainTime

A wall-clock time without date or time zone.

Instant

A precise moment in time.

ZonedDateTime

Date and time connected to a named time zone.

Examples

Make the date-time concept visible in the code.

Choose the Temporal type that matches the concept

const calendarDate = Temporal.PlainDate.from("2026-01-01");
const exactInstant = Temporal.Instant.from("2026-01-01T09:30:00Z");

console.log(calendarDate.toString());
console.log(exactInstant.toString());

Using Date for every time concept

const calendarDate = new Date("2026-01-01");

// A calendar date is now forced into instant/time-zone behavior.

Code patterns

Reusable examples for quick reference.

Dates and time zones become much easier when every example names the concept it represents: instant, local display, UTC output, calendar date, formatted text or zoned time.

Feature detect Temporal

Check support before using the API directly.

if ("Temporal" in globalThis) {
  console.log("Temporal is available.");
} else {
  console.log("Use a fallback or polyfill.");
}

Plain calendar date

Use PlainDate when the concept has no time zone.

const date = Temporal.PlainDate.from("2026-01-01");
const nextWeek = date.add({ days: 7 });

console.log(nextWeek.toString());

Exact instant

Use Instant for one precise point in time.

const instant = Temporal.Instant.from("2026-01-01T09:30:00Z");

console.log(instant.epochMilliseconds);

Zoned date-time

Use ZonedDateTime when a named time zone matters.

const zoned = Temporal.ZonedDateTime.from(
  "2026-01-01T09:30:00+01:00[Europe/Amsterdam]"
);

console.log(zoned.toString());

Rules that matter

Separate storage, logic and display.

Date-time bugs usually start when storage format, calculation logic and user-facing display are treated as the same thing. Keep those responsibilities separate and the code becomes much easier to trust.

Feature detect first

Do not assume Temporal exists everywhere.

Pick the right type

PlainDate, Instant and ZonedDateTime mean different things.

Use PlainDate for calendar dates

Birthdays, deadlines and day-only values often do not need a time zone.

Use Instant for exact moments

Logs and timestamps represent points in time.

Use ZonedDateTime for named zones

A time zone is part of the meaning.

Avoid mixing Date habits into Temporal

Temporal methods generally return new values instead of mutating the original.

Production thinking

Time is a data-modeling problem before it is a formatting problem.

Why does this matter?

Temporal makes date-time code more explicit. That lowers the chance of mixing calendar dates, exact instants and time-zone display by accident.

Accessibility

Clear date-time models make it easier to produce unambiguous visible text for users.

Production note

Production Temporal usage should include support checks, fallback strategy and tests for time-zone behavior.

SEO note

Temporal can help generate consistent visible and machine-readable date values, but output still needs correct formatting.

Live code lab

Change the HTML, CSS or JavaScript and run the result.

The preview runs inside an isolated iframe. The JavaScript is placed inside the HTML editor for now, so every example stays together and remains easy to understand.

Mini assignment

Try this now.

Change add({ days: 7 }) to add({ months: 1 }).
Add a fallback Date example for browsers without Temporal.
Write a second feature check for crypto.randomUUID as comparison.

Practice assignment

Do this before moving to the next topic.

Write a Temporal feature detection check.
Create a PlainDate from an ISO date string.
Explain when Instant is a better concept than PlainDate.

HTML + JavaScript CSS

Live preview

Self-check

Before you continue, prove that you understand Temporal.