JavaScript Temporal
What is JavaScript Temporal?
From 2026, the Temporal API will be the standard for date and time management in JavaScript, designed to replace the legacy Date object.
Unlike Date, Temporal objects are immutable and provide first-class support for time zones and non-Gregorian calendars.
Temporal separates date and time into distinct classes to prevent "wall-clock" errors.
Creating Temporal Date Objects
Temporal date objects can be created in different ways.
The most conmmon are:- Temporal.PlainDate()
- Temporal.PlainDate.from()
Temporal.PlainDate()
The Temporal.PlainDate() method creates a temporal date object with no time zone.
The Temporal.PlainDate() method above:
- Uses a direct constructor call
- Expects numeric arguments: (year, month, day).
- Takes values as-is and validates directly
Temporal.PlainDate.from()
Temporal.PlainDate.from() also lets you to create a date with no time zone:
The Temporal.PlainDate.from()method above:
- Parses values using ISO 8601 parsing rules
- Accept strings, objects, or other temporals:
- "2026-05-01"
- { year:2026, month:5, day:1 }
- PlainDate object
Note
Parsing means validation pluss automatic conversion.
When to Use Which?
Use new Temporal.PlainDate() when:
- You have trusted numeric values
- You want speed
- You want predictable construction
- You are doing date math
Use Temporal.PlainDate.from() when:
- You are handling user input (strings)
- You are handling external data (JSON)
- You want maximum flexibility
Main Temporal Objects
| Temporal.Now | The current time |
| Temporal.Instant | A fixed point in time, independent of time zone |
| Temporal.ZonedDateTime | Date and time in a specific time zone |
| Temporal.Duration | The difference between two time points |
Temporal PlainDate Objects
Plain dates are time-zone-unaware dates and times:
| Temporal.PlainDate | Calendar date only (2026-05-21) |
| Temporal.PlainTime | Time of day only (14:30:00) |
| Temporal.PlainDateTime | Full date and time (2026-01-24 14:30:00) |
| Temporal.PlainMonthDay | Month and day only (05-01) |
| Temporal.PlainYearMonth | Year and month only (2026-05) |
Temporal Now
The Temporal.Now object has methods for getting the current time in various formats.
Use zonedDateTimeISO() for the current system time:
Use the plainDateISO() for calender date only:
Temporal.PlainDate()
The Temporal.PlainDate() method creates a temporal date object with no time zone.
It returns an ISO 8601 calendar date without a time or time zone.
Return example: 2026-05-01.
Temporal.PlainTime()
The Temporal PlainTime() method creates a time object with no date.
It returns an ISO 8601 wall-clock time without a date or time zone.
Return example: 10:30:00.
Temporal.PlainDateTime()
The PlainDateTime() method creates a temporal date and time object.
It returns a calendar date and a wall-clock time with no time zone.
Return example: 2026-05-01T10:00:00.
Note
A PlainDateTime is essentially the combination of a Temporal.PlainDate() and a Temporal.PlainTime().
Temporal.PlainMonthDay()
The Temporal.PlainMonthDay() method create a temporal month and day object.
It returns the month and day of an ISO 8601 calendar date, without a year or a time zone.
Return example: 05-01.
Temporal.PlainYearMonth()
The Temporal.PlainYearMonth() method creates a temporal time and year object.
It returns the year and month of an ISO 8601 calendar date, without a day or a time zone.
Return example: 2026-05.
Manipulate Dates
Modify Temporal objects with add() and subtract().
Because they are immutable, these methods return new Temporal objects.
Example
const myDate = Temporal.PlainDate.from('2026-05-01');
const nextWeek = myDate.add({ days: 7 });
Try it Yourself »
Example
const myDate = Temporal.PlainDate.from('2026-05-01');
const lastWeek = myDate.subtract({ days: 7 });
Try it Yourself »
Date Comparison
Always use the .equals() or .compare() methods rather than standard equality operators:
Example
const date1 = Temporal.PlainDate.from('2026-05-01');
const date2 = Temporal.PlainDate.from('2026-05-01');
let result = date1.equals(date2);
Try it Yourself »
Difference Between Date and Temporal
- Date mixes date and time zone
- Date parsing is inconsistent
- Date is 0-based / Temporal is 1-based
Date and Time Zone
new Date(2026, 4, 1) creates a timestamp of your local time zone at midnight.
This means it can "shift" when you format it in UTC or in another zone.
Example
// Months are 0-based (4 = May)
const d = new Date(2026, 4, 1);
// Might be 2026-04-30T22:00:00.000Z in some time zones:
d.toISOString();
Temporal.PlainDate is not a timestamp.
It is just "2026-05-01" with no time and no time zone, so there can not be any shifting.
Date Parsing is Inconsistent
new Date("2026-05-01") parses as an instant (often treated as UTC by spec in modern JS),
but historically it has been a minefield of different formats, browser quirks and locale surprises.
Temporal avoids this by:
- defining strict parsing rules for ISO strings
- using Temporal.Instant.from() for clearly-typed conversions
Temporal is 1-Based
- Date: January = 0
- Temporal: January = 1 (much more human-friendly)
Example
// May 1:
new Date(2026, 4, 1)
// May 1:
new Temporal.PlainDate(2026, 5, 1)
