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:
Learn More:
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.
Learn More:
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.
Learn More:
Temporal Plain Objects
| 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 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.
Temporal.PlainDate Methods
| Method | Description |
|---|---|
| from() | Returns a new PlainDate object from another object or a string |
| toPlainDateTime() | Returns a new PlainDateTime object |
| toPlainMonthDay() | Returns a new PlainMonthDay object |
| toPlainYearMonth() | Returns a new PlainYearMonth object |
| toPlainMonthDay() | Returns a new PlainMonthDay object |
| toZonedDateTime() | Returns a new ZonedDatetime object |
| Arithmetic | |
| add() | Returns a new PlainDate with a duration added |
| subtract() | Returns a new PlainDate with a duration subtracted |
| with() | Returns a new PlainDate with specified fields modified |
| withCalendar() | Returns a new PlainDate with a different calendar system |
| Comparison | |
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two PlainDate objects are identical |
| since() | Returns the difference since another date |
| until() | Returns the difference until another date |
| Formatting | |
| toString() | Returns an ISO 8601 string representation |
| toJSON() | Returns an ISO 8601 string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainDate Properties
The Temporal.PlainDate object has 16 properties of calendar date information.
| 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:
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 |
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.
The Temporal.PlainTime Object
The Temporal PlainTime object is a time object with no date.
It represents an ISO 8601 wall-clock time without a date or time zone.
Example: 14:30:00.
Temporal PlainTime Methods
| Method | Description |
|---|---|
| from() | Returns a new PlainTime object from another object or a string |
| Arithmetic | |
| add() | Returns a new PlainTime with a duration added |
| subtract() | Returns a new PlainTime with a duration subtracted |
| round() | Returns a new PlainTime rounded to a given unit |
| with() | Returns a new PlainTime with specified fields modified |
| Comparison | |
| compare() | Returns -1, 0, or 1 from comparing two times |
| equals() | Returns true if two PlainTime objects are identical |
| since() | Returns the difference since another time |
| until() | Returns the difference until another time |
| Formatting | |
| toString() | Returns an ISO 8601 string representation |
| toJSON() | Returns an ISO 8601 string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainTime Properties
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) |
The Temporal.PlainDateTime Object
The PlainDateTime() objects ios a temporal date and time object.
It represents a calendar date and a wall-clock time with no time zone.
Example: 2026-05-07T14:30:00.
Note
A PlainDateTime is essentially the combination of a Temporal.PlainDate() and a Temporal.PlainTime().
Temporal.PlainDateTime Methods
| Method | Description |
|---|---|
| from() | Returns a new PlainDateTime object from another object or a string |
| toPlainDate() | Returns a new PlainDate object |
| toPlainTime() | Returns a new PlainTime object |
| toZonedDateTime() | Returns a new ZonedDatetime object |
| with() | Returns a new PlainDateTime with specified fields modified |
| withCalendar() | Returns a new PlainDateTime with a different calendar system |
| withPlainTime() | Returns a new PlainDateTime the time part replaced by a new time |
| Arithmetic | |
| add() | Returns a new PlainDateTime with a duration added |
| subtract() | Returns a new PlainDateTime with a duration subtracted |
| round() | Returns a new PlainDateTime rounded to a given unit |
| Comparison | |
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two PlainDateTime objects are identical |
| since() | Returns the difference from another date |
| until() | Returns the difference until another date |
| Formatting | |
| toString() | Returns an ISO 8601 string representation |
| toJSON() | Returns an ISO 8601 string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainDateTime Properties
The Temporal.PlainDateTime object has 22 properties of calendar date information.
| 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.Duration Methods
| Method | Description |
|---|---|
| from() | Returns a new Duration object from another object or a string |
| Arithmetic | |
| add() | Returns a new Duration with a duration added |
| subtract() | Returns a new Duration with a duration subtracted |
| abs() | Returns a new Duration with the absolute value |
| negated() | Returns a new Duration with the negated value |
| round() | Returns a new Duration rounded to a given unit |
| with() | Returns a new Duration with specified fields modified |
| Comparison | |
| compare() | Comparing two times (returning -1, 0, or 1) |
| Formatting | |
| total() | Returns a number representing the duration in a given unit |
| toString() | Returns an ISO 8601 string representation |
| toJSON() | Returns an ISO 8601 string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.Duration Properties
The Temporal.Duration object has 12 properties of time information.
Learn More:
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.round() | New temporal rounded down to specified unit |
Temporal Comparison
| Method | Description |
|---|---|
| temporal.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.since() | The duration between two temporal objects |
| temporal.until() | The duration between two temporal objects |
