JS Temporal Reference
Main Temporal Objects
Temporal objects are the core part of theTemporal APIwhich aims to replace theold Date object.
All Temporal objects are immutable, which helps prevent bugsrelated 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
TheTemporal.Now object has methods for getting the current time in various formats.
Use theTemporal.Now.zonedDateTimeISO() method for current system time:
Use theTemporal.Now.plainDateISO() method for calender date only:
Temporal.ZonedDateTime
ATemporal.ZonedDateTime is a timezone and calendar-awaredate/time object that represents a real time event from the perspective of a particularregion on Earth.
Example: December 7th, 1995 at 3:24 AM in US Pacific time (in Gregorian calendar).
Example
timeZone: 'America/Los_Angeles',
year: 1995,
month: 12,
day: 7,
hour: 3,
minute: 24,
second: 30,
millisecond: 0,
microsecond: 3,
nanosecond: 500
});
TheTemporal.ZonedDateTime object is optimized for cases thatrequire a time zone,DST-safe arithmetic and interoperability with anRFC 5545 calendar.
The Temporal.Instant Object
Temporal.Instant is a JavaScript object representing asingle point in time.
Temporal.Instant hasno time zone or calendar.
Temporal.Instant stores a count ofnanoseconds sincethe 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 aTemporal.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
TheTemporal.PlainDate object has16 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()
TheTemporal PlainTime() method creates a time object with no date.
It returns an ISO 8601wall-clock time without a date or time zone.
Return example:10:30:00.
The Temporal.PlainTime Object
TheTemporal.PlainTime object has6 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()
ThePlainDateTime() method creates a temporal date and time object.
It returns acalendar date and awall-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
TheTemporal.PlainDateTime has22 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()
TheTemporal.PlainYearMonth() method creates a temporal time and year object.
It returns theyear andmonth of an ISO 8601 calendar date, without a day or a time zone.
Return example:2026-05.
The Temporal.PlainYearMonth Object
TheTemporal.PlainYearMonth has10 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()
TheTemporal.PlainMonthDay() method create a temporal month and day object.
It returns themonth andday of an ISO 8601 calendar date, without a year or a time zone.
Return example:05-01.
The Temporal.PlainMonthDay Object
TheTemporal.PlainMonthDay has3 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
.from(...) defaults to ISO 8601.
You CANNOT add a calendar parameter, but if the input string includes a calendar, it is used:
