JS Temporal Reference
Temporal Objects
Temporal objects are the core part of the Temporal API
which aims to replace the old Date object.
Note
All Temporal objects are immutable, which helps prevent bugs
related to accidental modification of time values.
Temporal.Duration Methods
|
| Method | Description |
|---|
| compare() | Comparing two durations (returning -1, 0, or 1) |
| from() | Returns a new duration from an object or an ISO string |
| with() | Returns a new duration with specified field(s) modified |
| Arithmetic | |
|---|
| abs() | Returns a new duration with the absolute value of this duration |
| add() | Returns a new duration with a duration added to this duration |
| negated() | Returns a new duration with this duration negated |
| round() | Returns a new duration with this duration rounded |
| subtract() | Returns a new duration with a duration subtracted from this duration |
| Formatting | |
|---|
| total() | Returns a number representing the duration in a given unit |
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the time |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.Duration Properties
|
| Property | Description |
|---|
| blank | Boolean true if the duration represents a zero duration |
| days | Days as an integer (1-31) |
| hours | Hours as an integer (0-23 |
| microseconds | Microseconds as an integer (0-999) |
| milliseconds | Milliseconds as an integer (0-999) |
| minutes | Minutes as an integer (0-59) |
| months | Months as an integer (1-12) |
| nanoseconds | Nanoseconds as an integer (0-999) |
| seconds | Seconds as an integer (0-59) |
| sign | 1 positive -1 negative |
| weeks | Weeks as an integer |
| years | Years as an integer |
Temporal.Now Methods
|
| Method | Description |
|---|
| instant() |
Returns current time as a Temporal.Instant object |
| plainDateISO() |
Returns current date as a Temporal.PlainDate object |
| plainDateTimeISO() |
Returns current date and time as a Temporal.PlainDateTime object |
| plainTimeISO() |
Returns current time as a Temporal.PlainTime object |
| timeZoneId |
Returns system's time zone as a time zone id |
| zonedDateTimeISO() |
Returns current date and time as a Temporal.ZonedDateTime object |
Temporal.Instant Methods
|
| Constructing | |
|---|
| new | Creates a new Temporal.Instant object |
| from() | Creates a new Instant object from another instant or a string |
| fromEpochMilliseconds() | Returns a new Instant object from a number of milliseconds |
| fromEpochNanoseconds() | Returns a new Instant object from a number of nanoseconds |
| Arithmetic | |
|---|
| add() | Returns a new Instant with a duration added |
| round() | Returns a new Instant with this instant rounded |
| subtract() | Returns a new Instant with a duration subtracted |
| Comparing | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two instants |
| equals() | Returns true if two instants are identical |
| since() | Returns the duration since another date |
| until() | Returns the duration until another date |
| Converting | |
|---|
| toZonedDateTimeISO() | Returns a new ZonedDatetime object |
| Formatting | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the instant |
| toString() | Returns an RFC 9557 format string representation of the instant |
| valueOf() | Throws a TypeError (Instants should not be converted to a primitives) |
Temporal ZonedDateTime Methods
|
| Method | Description |
|---|
| from() | Returns a new ZonedDateTime object from an object or a string |
getTimeZone
Transition() | Returns a ZonedDateTime object representing the closest
instant after or before this instant |
| startOfDay() | Returns a ZonedDateTime object representing the first instant of this date |
| toInstant() | Returns a new Instant object representing this date-time |
| toPlainDate() | Returns a new PlainDate object representing this date-time |
| toPlainDateTime() | Returns a new PlainDateTime object representing this date-time |
| toPlainTime() | Returns a new PlainTime object representing this date-time |
| with() | Returns a new ZonedDateTime with specified fields modified |
| withCalendar() | Returns a new ZonedDateTime with a different calendar system |
| withPlainTime() | Returns a new ZonedDateTime the time part replaced by a new time |
| withTimeZone() | Returns a new ZonedDateTime object representing this date-time in the new time zone |
| Arithmetic | |
|---|
| add() | Returns a new ZonedDateTime with a duration added |
| subtract() | Returns a new ZonedDateTime with a duration subtracted |
| round() | Returns a new ZonedDateTime rounded to a given unit |
| Comparison | |
|---|
| compare() | Returns -1, 0, or 1 from comparing two dates |
| equals() | Returns true if two ZonedDateTime 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 ZonedDateTime Properties
|
| 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 |
| epochMilliseconds | Number of milliseconds since Unix epoch |
| epochNanoseconds | Number of nanoseconds since Unix epoch |
| 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) |
| hoursInDay | Hours in this day in this time zone(0-25) |
| 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) |
| offset | Offset used to interpret this instant (+HH:mm:ss.sssssssss) |
| offsetNanoseconds | Offset used to interpret this instant in nanoseconds |
| second | The second as an integer (0-59) |
| timeZoneId | Time zone identifier used to interpret this instant |
| weekOfYear | The week number within the year |
| year | The year as an integer |
| yearOfWeek | The year that the week belongs to |
Display All Properties
const zoned = Temporal.ZonedDateTime.from("2026-05-17T14:30:00[Europe/Oslo]");
Try it Yourself »
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) |
Temporal.PlainDate Methods
|
| Constructing | Description |
|---|
| from() | Creates a new PlainDate object from an object or a string |
| new | Creates a new PlainDate object from (year, month, day) |
| Arithmetic | |
|---|
| add() | Returns a new PlainDate with a duration added |
| subtract() | Returns a new PlainDate with a duration subtracted |
| Comparing | |
|---|
| 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 |
| Converting | |
|---|
| toPlainDateTime() | Returns a new PlainDateTime object |
| toPlainMonthDay() | Returns a new PlainMonthDay object |
| toPlainYearMonth() | Returns a new PlainYearMonth object |
| toZonedDateTime() | Returns a new ZonedDatetime object |
| with() | Returns a new PlainDate with specified fields modified |
| withCalendar() | Returns a new PlainDate with a different calendar system |
| Formatting | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (should not be converted to primitives) |
Temporal.PlainDate Properties
|
| 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 |
Display All Properties
const date = new Temporal.PlainDate(2026, 5, 17);
Try it Yourself »
Temporal.PlainYearMonth Methods
|
| Method | Description |
|---|
| from() | Returns a new PlainDate object from another object or a string |
| toPlainDate() | Returns a new PlainDate object |
| with() | Returns a new PlainDate with specified fields modified |
| Arithmetic | |
|---|
| add() | Returns a new PlainDate with a duration added |
| subtract() | Returns a new PlainDate with a duration subtracted |
| 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 | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainYearMonth Properties
|
| 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 Methods
|
| Method | Description |
|---|
| equals() | Returns true if two PlainDate objects are identical |
| from() | Returns a new PlainDate object from another object or a string |
| toPlainDate() | Returns a new PlainDate object |
| with() | Returns a new PlainDate with specified fields modified |
| withCalendar() | Returns a new PlainDate with a different calendar system |
| Formatting | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() | Returns a language-sensitive representation of the date |
| toString() | Returns an RFC 9557 format string representation |
| valueOf() | Throws a TypeError (prevents temporals from being converted to primitives) |
Temporal.PlainMonthDay Properties
|
| 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") |
Temporal PlainTime Methods
|
| Constructing | 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 |
| Comparing | |
|---|
| 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 |
| Converting | |
|---|
| with() | Returns a new PlainTime with specified fields modified |
| Formatting | |
|---|
| toString() | Returns an RFC 9557 format string representation |
| toJSON() | Returns an RFC 9557 format 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
|
| 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 Methods
|
| Constructing | Description |
|---|
| from() |
Creates a PlainDateTime object from an object or a string |
| new |
Creates a PlainDateTime object from parameters |
| Arithmetic | |
|---|
| add() |
Returns a PlainDateTime with a duration added |
| subtract() |
Returns a PlainDateTime with a duration subtracted |
| round() |
Returns a PlainDateTime rounded to a given unit |
| Comparing | |
|---|
| 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 PlainDateTime |
| until() |
Returns the difference until another PlainDateTime |
| Converting | |
|---|
| toPlainDate() |
Returns a PlainDate object with the date from this PlainDateTime |
| toPlainTime() |
Returns a PlainTime object with the time from this PlainDateTime |
| toZonedDateTime() |
Returns a ZonedDatetime object with this PlainDateTime in a time zone |
| with() |
Returns a PlainDateTime with specified fields modified |
| withCalendar() |
Returns a PlainDateTime with a different calendar system |
| withPlainTime() |
Returns a PlainDateTime with the time part replaced by a new time |
| Formatting | |
|---|
| toJSON() | Returns an RFC 9557 format string for JSON serialization |
| toLocaleString() |
Returns a language-sensitive representation of the date |
| toString() |
Returns an RFC 9557 format string representation of the date |
| valueOf() |
Throws an error to prevents temporals from being converted to primitives |
Temporal.PlainDateTime Properties
|
| 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 |
Display All Properties
const date = new Temporal.PlainDateTime(2026, 5, 1, 14, 30);
Try it Yourself »
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 |
