Suggest an edit

Improve this article

Refine the answer for “What is the Temporal API?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

The **Temporal API** is a **new built-in API for working with dates and time** in JavaScript (officially at the final-standard stage as of ES2024).
Its goal is to **replace the "broken"** `Date` and provide precise, safe, convenient tools for all time-related operations.

## Why Temporal was created at all

`Date` is one of the oldest and most problematic parts of JS (dating back to 1995):

| Problem | Example |
|---|---|
| Implicit time zones | `new Date('2024-01-01')` -> the result depends on your region |
| Unpredictable calculations | `new Date(2024, 1, 30)` -> March 1 |
| Mutating methods | `setMonth()`, `setHours()` mutate the original object |
| Poor UTC handling | You often need to convert manually via `toISOString()`, `getUTC*()` |
| No proper API for calendars, durations, and time zones | |

`Temporal` solves **all of these problems** by introducing a **clear model of time** and **immutable objects**.

## The main idea behind the Temporal API

Temporal provides **new classes** that work with different aspects of time:

| Class | What it represents | Example |
|---|---|---|
| `Temporal.Instant` | A moment in time (a point in UTC) | `"2025-10-16T21:00:00Z"` |
| `Temporal.PlainDate` | A date without a time | `"2025-10-16"` |
| `Temporal.PlainTime` | A time without a date | `"21:00:00"` |
| `Temporal.PlainDateTime` | A date and time without a time zone | `"2025-10-16T21:00:00"` |
| `Temporal.ZonedDateTime` | Date + time + time zone | `"2025-10-16T21:00:00+02:00[Europe/Warsaw]"` |
| `Temporal.Duration` | The difference between two moments (a duration) | `"P3DT5H"` (3 days 5 hours) |
| `Temporal.Now` | A utility for getting the current time | - |

## Example: creating a date and time

```javascript
// A plain date
const date = Temporal.PlainDate.from('2025-10-16');
console.log(date.year, date.month, date.day); // 2025 10 16

// A time
const time = Temporal.PlainTime.from('13:45:30');
console.log(time.hour); // 13

// A date and time
const dt = Temporal.PlainDateTime.from('2025-10-16T13:45:30');
console.log(dt.toString()); // 2025-10-16T13:45:30
```

## Example: working with time zones

```javascript
const zdt = Temporal.ZonedDateTime.from({
  timeZone: 'Europe/Warsaw',
  year: 2025,
  month: 10,
  day: 16,
  hour: 21,
});

console.log(zdt.toString());
// 2025-10-16T21:00:00+02:00[Europe/Warsaw]

console.log(zdt.toInstant().toString());
// 2025-10-16T19:00:00Z (in UTC)
```

Temporal stores the time zone as part of the data (`[Europe/Warsaw]`),
not just an offset like `+02:00`.

## Example: calculations with dates and time

```javascript
const today = Temporal.PlainDate.from('2025-10-16');
const tomorrow = today.add({ days: 1 });
const lastWeek = today.subtract({ weeks: 1 });

console.log(tomorrow.toString()); // 2025-10-17
console.log(lastWeek.toString()); // 2025-10-09
```

All objects are **immutable**; operations return new values
instead of changing the original object.

## Example: calculating a duration

```javascript
const start = Temporal.PlainDateTime.from('2025-10-16T10:00');
const end = Temporal.PlainDateTime.from('2025-10-18T15:30');

const duration = end.since(start);
console.log(duration.toString()); // P2DT5H30M (2 days 5 hours 30 minutes)
```

## Example: the current time and the time in a zone

```javascript
const now = Temporal.Now.instant();
console.log(now.toString()); // The current UTC time

const warsaw = Temporal.Now.zonedDateTimeISO('Europe/Warsaw');
console.log(warsaw.toString());
// For example: 2025-10-16T23:50:00+02:00[Europe/Warsaw]
```

## Example: the difference from `Date`

```javascript
// Date
new Date(2025, 1, 30) // 2025-03-02 (!) -> an automatic "rollover"

// Temporal
Temporal.PlainDate.from({ year: 2025, month: 1, day: 30 });
// RangeError: Invalid PlainDate
```

Temporal **strictly validates dates**; there are no "automatic corrections".

## Example: formatting and parsing ISO strings

```javascript
const zdt = Temporal.ZonedDateTime.from('2025-10-16T21:00+02:00[Europe/Warsaw]');
console.log(zdt.toString()); // 2025-10-16T21:00:00+02:00[Europe/Warsaw]
```

It supports the full ISO 8601 format and works with time zones through the IANA database (the same one used by `Intl.DateTimeFormat`).

## Example: using it with `Intl`

You can conveniently format dates and times for the user:

```javascript
const zdt = Temporal.ZonedDateTime.from('2025-10-16T21:00:00+02:00[Europe/Warsaw]');
const fmt = new Intl.DateTimeFormat('en-US', { dateStyle: 'full', timeStyle: 'long' });

console.log(fmt.format(zdt));
// Thursday, October 16, 2025 at 9:00:00 PM GMT+2
```

## Example: safely handling time zones

```javascript
const beforeDST = Temporal.ZonedDateTime.from('2025-03-30T01:30:00+01:00[Europe/Berlin]');
const afterDST = beforeDST.add({ hours: 1 });
console.log(afterDST.toString());
// 2025-03-30T03:30:00+02:00[Europe/Berlin]
```

Temporal **understands daylight saving transitions**
and shifts the hours correctly.

## Benefits of the Temporal API

| Benefit | What it gives |
|---|---|
| Immutability | Safe operations without mutations |
| A clear model | Separation of the concepts "date", "time", "zone" |
| Accurate time zone handling | Uses the IANA database |
| No `Date` "magic" | Errors instead of silent corrections |
| Compatible with `Intl` | Clean formatting |
| ISO and Duration support | Simple handling of differences and intervals |

## Where it can already be used

- Node.js 20+ - **built in natively**
- Modern browsers (Chrome 115+, Firefox 122+, Edge 115+)
- Older environments - via a **polyfill**
`@js-temporal/polyfill`

```javascript
npm i @js-temporal/polyfill
```

```javascript
import { Temporal } from '@js-temporal/polyfill';
```

## Summary

| Object | Description |
|---|---|
| `Temporal.Instant` | an absolute point in time (UTC) |
| `Temporal.PlainDate`, `PlainTime`, `PlainDateTime` | local values without a zone |
| `Temporal.ZonedDateTime` | date + time + time zone |
| `Temporal.Duration` | a duration (a time difference) |
| `Temporal.Now` | access to the current time |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts810 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.