For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/year/2027/proposal-temporal.md.
TC39 Atlas
  • English

      • Temporal S4

      Proposal details
      Proposal overview

      This proposal introduces the Temporal global object, a modern date/time API for ECMAScript that addresses long-standing issues with the Date object. It provides immutable objects supporting multiple calendar systems and a standard 24-hour clock.js, and is being incorporated into ECMA-262 and ECMA-402.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Temporal

      Provides standard objects and functions for working with dates and times.

      Status

      This proposal is currently Stage 4.

      It will be merged into the ECMA-262 and ECMA-402 standards and this repository will be archived.

      Implementation status:

      Champions

      Overview / Motivation

      Date has been a long-standing pain point in ECMAScript. This proposes Temporal, a global Object that acts as a top-level namespace (like Math), that brings a modern date/time API to the ECMAScript language. For a detailed breakdown of motivations, see: Fixing JavaScript Date

      Principles:

      • All Temporal objects are immutable.
      • Date values can be represented in local calendar systems (why?), but they should be convertable to and from the Proleptic Gregorian Calendar.
      • All time-of-day values are based on a standard 24-hour clock.
      • Leap seconds are not represented.

      Specification Text

      The specification text can be found here.

      Documentation

      Reference documentation and examples can be found below.

      A cookbook to help you get started and learn the ins and outs of Temporal is available here

      Polyfills

      PolyfillRepoStatus
      @js-temporal/polyfilljs-temporal/temporal-polyfillAlpha release available
      temporal-polyfillfullcalendar/temporal-polyfillStable release available
      temporal-polyfill-litefabon-f/temporal-polyfill-liteRelease Candidate available

      If you're working on a polyfill, please file an issue or PR so we can add yours here.

      A non-production polyfill was built to validate this proposal. This polyfill continues to live in this repo, but only for the purposes of running tests and powering the documentation "playground" as described below.

      DO NOT use this polyfill in your own projects! Instead, please use a polyfill from the table above.

      Documentation Playground

      When viewing the reference documentation, the non-production polyfill is automatically loaded in your browser, so you can try out Temporal by opening your browser's developer tools console.