JS Temporal Reference
Main Temporal Objects
Temporal objects are the core part of the Temporal API which aims to replace the old Date object.
All Temporal objects are immutable, which helps prevent bugs related to accidental modification of time values.
| Object | Description |
|---|---|
| Temporal.Now | The current time |
| Temporal.ZonedDateTime | Date and time in a specific time zone |
| Temporal.Instant | A fixed point in time, independent of time zone |
Plain 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.PlainYearMonth() | Year and month only (2026-05) |
| Temporal.PlainMonthDay() | Month and day only (05-01) |
Temporal.Now
The Temporal.Now object has methods for getting the current time in various formats.
Use the Temporal.Now.zonedDateTimeISO() method for current system time:
Use the Temporal.Now.plainDateISO() method for calender date only:
Temporal.ZonedDateTime
A Temporal.ZonedDateTime is a timezone and calendar-aware
date/time object that represents a real time event from the perspective of a particular
region on Earth.
Example: December 7th, 1995 at 3:24 AM in US Pacific time (in Gregorian calendar).
Example
const zonedDate = Temporal.ZonedDateTime.from({
timeZone: 'America/Los_Angeles',
year: 1995,
month: 12,
day: 7,
hour: 3,
minute: 24,
second: 30,
millisecond: 0,
microsecond: 3,
nanosecond: 500
});
Try it Yourself »
The Temporal.ZonedDateTime object is optimized for cases that
require a time zone, DST-safe arithmetic and interoperability with an RFC 5545 calendar.
The Temporal.Instant Object
Temporal.Instant is a JavaScript object representing a
single point in time.
Temporal.Instant has no time zone or calendar.
Temporal.Instant stores a count of nanoseconds since
the Unix epoch: January 1, 1970 00.00.
Note
Nanosecond precision is 1000 times higher than the millisecond precision of the old Date object.
Creating an Instant:
| From | Code |
| String | Temporal.Instant.from('1969-07-20T20:17:00Z') |
| Current time | Temporal.Now.instant() |
| Epoch millisec | Temporal.Instant.fromEpochMilliseconds() |
| Epoch nanosec | Temporal.Instant.fromEpochNanoseconds() |
Arithmetic and Comparison:
| Method | Description |
add() |
Adds a duration (hours, minutes, seconds) to an instant |
subtract() |
Subtracts duration (hours, minutes, seconds) to an instant |
compare() |
Returns -1 if the first date is earlier, 1 if later and 0 if equal |
equals() |
The Temporal.Instant.from() Method
To get human-readable components like year, month, or hour, you must explicitly convert it to a
Temporal.ZonedDateTime using a specific time zone.
Temporal PlainDate Objects
A Temporal.PlainDate object in JavaScript represents a calendar date (year, month, and day) without a specific time zone, typically in ISO 8601 format ("2026-05-01").
It is used for dates that remain the same regardless of time zone, such as birthdays or holidays:
| Object | Description |
|---|---|
| Temporal.PlainDate | Calendar date only (2026-05-21) |
| Temporal.PlainTime | Time of day only (14:30:00) |
| Temporal.PlainMonthDay | Month and day only (05-01) |
| Temporal.PlainYearMonth | Year and month only (2026-05) |
The Temporal.PlainDate Object
The Temporal.PlainDate object has 16 properties of calendar date information.
These include calendar identification, day/month/year details, era information and other calendar metrics:
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable |
| eraYear | The year within the era, if applicable |
| inLeapYear | A boolean indicating if the year is a leap year |
| month | The month as an integer (1-12) |
| monthCode | A string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
Learn More:
Note
A PlainDate object is essentially the date part of a Temporal.PlainDateTime object, with the time information removed.
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.
The Temporal.PlainTime Object
The Temporal.PlainTime object has 6 properties of time information.
| Property | Description |
| hour | The hour as an integer (0-23 |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| nanosecond | The nanosecond as an integer (0-999) |
| second | The second as an integer (0-59) |
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().
The Temporal.PlainDateTime Object
The Temporal.PlainDateTime has 22 properties of calendar date information.
These include calendar id, day/month/year/time, era information and various calendar metrics:
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| dayOfWeek | The day of the week as an integer (1 = Monday) |
| dayOfYear | The ordinal day of the year |
| daysInMonth | The total number of days in that month |
| daysInWeek | The total number of days in that week |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable ("gregory") |
| eraYear | The year within the era, if applicable |
| hour | The hour as an integer (0-23 |
| inLeapYear | A boolean indicating if the date falls in a leap year |
| microsecond | The microsecond as an integer (0-999) |
| millisecond | The millisecond as an integer (0-999) |
| minute | The minute as an integer (0-59) |
| month | The month as an integer (1-12) |
| monthCode | A calendar-specific string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| nanosecond | The nanosecond as an integer (0-999) |
| second | The second as an integer (0-59) |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
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.
The Temporal.PlainYearMonth Object
The Temporal.PlainYearMonth has 10 properties of calendar date information.
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| daysInMonth | The total number of days in that month |
| daysInYear | The total number of days in that year |
| era | The era name of the calendar, if applicable ("gregory") |
| eraYear | The year within the era, if applicable |
| inLeapYear | A boolean indicating if the date falls in a leap year |
| month | The month as an integer (1-12) |
| monthCode | A calendar-specific string code for the month ("M01") |
| monthsInYear | The total number of months in that year |
| year | The year as an integer |
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.
The Temporal.PlainMonthDay Object
The Temporal.PlainMonthDay has 3 properties of calendar date information.
| Property | Description |
| calendarID | Calendar system identifier ("iso8601") |
| day | The day as an integer (1-31) |
| monthCode | A calendar-specific string code for the month ("M01") |
Note
The Temporal.PlainMonthDay object does not have a month property.
Temporal Arithmetic
| Method | Returns |
|---|---|
| temporal.add() | New temporal representing a date moved forward by a duration |
| temporal.subtract() | New temporal representing a date moved backward by a duration |
| temporal.since() | The duration between two temporal objects |
| temporal.until() | The duration between two temporal objects |
| temporal.with() | New temporal with fields replaced (change a day) |
Temporal Comparison
| Method | Description |
|---|---|
| Temporal.PlainDate.compare() | Static method useful for sorting arrays of dates (returns -1, 0, or 1) |
| temporal.equals() | Returns true if two dates (and their calendars) are identical |
| Temporal.Duration | The difference between two time points |
Learn More:
Temporal Calendars
new Temporal.PlainDate(...) defaults to ISO 8601.
If you want a specific calendar, you CAN add a calendrer parameter:
Example
new Temporal.PlainDate(2026, 5, 1, 'iso8601')
.from(...) defaults to ISO 8601.
You CANNOT add a calendar parameter, but if the input string includes a calendar, it is used:
Example
Temporal.PlainDate.from('2026-05-01[u-ca=iso8601]')
