Codectionary / Developer documentation / JavaScript

Temporal API

Temporal is the modern, immutable replacement for the long-criticized Date object, reaching TC39 Stage 4 and becoming part of the ECMAScript 2026 specification. It fixes Date's biggest pain points: no built-in time zone support, confusing zero-indexed months, and mutable objects that are easy to accidentally modify. Temporal provides distinct types for different use cases - PlainDate, PlainTime, ZonedDateTime, Duration, and more.

Syntax

Temporal.Now.plainDateISO()
Temporal.ZonedDateTime.from(...)

Examples

Getting the Current Date and Time

Temporal separates "what date is it" from "what time is it" into distinct, purpose-built types.

const today = Temporal.Now.plainDateISO();
console.log(today.toString()); // e.g. "2026-07-20"

const now = Temporal.Now.zonedDateTimeISO("Europe/London");
console.log(now.toString()); // includes an explicit, real IANA time zone

Immutable Date Arithmetic

Every operation returns a new object - the original is never mutated, unlike Date.

const date = Temporal.PlainDate.from("2026-01-15");
const nextMonth = date.add({ months: 1 });

console.log(date.toString());      // "2026-01-15" - unchanged
console.log(nextMonth.toString());  // "2026-02-15" - a brand new object

Real Time Zone Support

Working correctly across time zones, something the legacy Date object could never do natively.

const meeting = Temporal.ZonedDateTime.from({
  timeZone: "America/New_York",
  year: 2026, month: 8, day: 10,
  hour: 14, minute: 0
});

const londonTime = meeting.withTimeZone("Europe/London");
console.log(meeting.toString());
console.log(londonTime.toString()); // same instant, correctly converted

Best practices

  • Use Temporal for new projects going forward - it directly solves the time zone and mutability problems that made Date libraries like moment.js and date-fns necessary
  • Check current browser/runtime support before relying on it in production without a polyfill - as of mid-2026 it ships natively in Chrome and Firefox, with Edge experimental and Safari still in Technical Preview
  • Choose the most specific Temporal type for your use case - PlainDate for a calendar date with no time/zone, ZonedDateTime when time zone matters, Duration for elapsed time
  • Use a polyfill (like @js-temporal/polyfill) for cross-browser compatibility until support is universal

Runtime & versions

Browsers and JavaScript runtimes. Feature availability depends on the language and runtime version used by your project; consult the official reference below.

ECMAScript specification

Specifications & further reading