Unlike most global objects, Temporal is not a constructor. You cannot use it with the new operator or invoke the Temporal object as a function. All properties and methods of Temporal are static (just like the Math object).

Temporal has an intricate and powerful API. It exposes over 200 utility methods via several classes, so it could appear very complex. We will provide a high-level overview of how these APIs are related to each other.

JavaScript has had the Date object for handling date and time since its first days. However, the Date API is based on the poorly designed java.util.Date class from Java, which was replaced in the early 2010s; but, because of JavaScript's goal of backward compatibility, Date sticks around in the language.

The important lesson to preface the whole introduction is that . Most of the problems of Date are fixable by adding more methods, but a fundamental design flaw remains: it exposes so many methods on the same object that developers are often confused about what to use, leading to unexpected pitfalls. A well-designed API not only needs to do more, but also should do less with each level of abstraction, because preventing misuse is as important as enabling use cases.

Date objects wear two hats simultaneously:

Time zones underlie a significant number of date-related bugs. When interacting with a Date via the "combination of components" model, the time can only be in two time zones: UTC and local (device), and there's no way to specify an arbitrary time zone. Also lacking is the concept of "no time zone": this is known as a calendar date (for dates) or wall-clock time (for times), which is a time you "read off a calendar or clock". For example, if you are setting a daily wake up alarm, you will want to set it to "8:00AM" regardless of whether it is daylight saving time or not, whether you have traveled to a different time zone, etc.

A second feature lacking from Date is a calendar system. Most people may be familiar with the Gregorian calendar, where there are two eras, BC and AD; there are 12 months; each month has a different number of days; there's a leap year every 4 years; and so on. However, some of these concepts may not apply when you are working with another calendar system, such as the Hebrew calendar, the Chinese calendar, the Japanese calendar, etc. With Date, you can only work with the Gregorian calendar model.

There are many other undesirable legacies about Date, such as all setters being mutating (which often causes unwanted side effects), the date time string format being impossible to parse in a consistent way, etc. In the end, the best solution is to build a new API from scratch, which is what Temporal is.

Temporal is a namespace, like Intl. It contains several classes and namespaces, each of which is designed to handle a specific aspect of date and time management. The classes can be grouped as such:

Furthermore, there's also another utility namespace, Temporal.Now, which provides methods for getting the current time in various formats.

The table below summarizes all conversion methods that exist on each class.

With these tables, you should have a basic idea of how to navigate the Temporal API.

A calendar is a way to organize days, typically into periods of weeks, months, years, and eras. Most of the world uses the Gregorian calendar, but there are many other calendars in use, especially in religious and cultural contexts. By default, all calendar-aware Temporal objects use the ISO 8601 calendar system, which is based on the Gregorian calendar and defines additional week-numbering rules. Intl.Locale.prototype.getCalendars() lists most of the calendars likely to be supported by browsers. Here we provide a brief overview of how calendar systems are formed to help you internalize what factors may vary between calendars.

There are three prominent periodic events on Earth: its rotation around the sun (365.242 days for one revolution), the moon's rotation around the Earth (29.53 days from new moon to new moon), and its rotation around its axis (24 hours from sunrise to sunrise). Every culture has the same measure of a "day", which is 24 hours. Occasional changes such as daylight saving time are not part of the calendar, but are part of the time zone's information.

In Temporal, every date under one calendar system is uniquely identified by three components: year, month, and day. year is an integer that may be zero or negative, which increases monotonously with time. The year 1 (or 0, if it exists) is known as the calendar epoch, and is arbitrary for each calendar. month is an integer that increments by 1 every time, starting at 1 and ending at date.monthsInYear, then resetting back to 1 as the year advances. day is also a positive integer, but it may not start at 1 or increment by 1 every time, because political changes may cause days to be skipped or repeated. But in general, day monotonously increases and resets as the month advances.

In addition to year, a year can also be uniquely identified by the combination of era and eraYear, for calendars that use eras. For example, the Gregorian calendar uses the era "CE" (Common Era) and "BCE" (Before Common Era), and the year -1 is the same as { era: "bce", eraYear: 1 }. era is a lowercase string, and eraYear is an arbitrary integer that may be zero or negative, or even decrease with time (usually for the oldest era).

In addition to month, a month in a year can also be uniquely identified by the monthCode. monthCode usually maps to the month's name, but month does not. For example, in the case of lunisolar calendars, two months with the same monthCode, where one belongs to a leap year and the other one does not, will have different month values if they come after the leap month, due to the insertion of an extra month.

In addition to day (which is a month-based index), a day in a year can also be uniquely identified by the dayOfYear. dayOfYear is a positive integer that increments by 1 every time, starting at 1 and ending at date.daysInYear.

The concept of a "week" is not connected with any astronomical event, but is a cultural construct. Therefore, weeks can have 4, 5, 6, 8, or more days, or not even a fixed number of days. To get the specific number of days of the week of a date, use the date's daysInWeek. Temporal identifies weeks by the combination of weekOfYear and yearOfWeek. weekOfYear is a positive integer that increments by 1 every time, starting at 1, then resetting back to 1 as the year advances. yearOfWeek is generally the same as year, but may be different at the start or end of each year, because one week may cross two years, and yearOfWeek picks one of the two years based on the calendar's rules.

All Temporal classes can be serialized and deserialized using the format specified in RFC 9557, which is based on ISO 8601 / RFC 3339. The format, in its full form, is as follows (spaces are only for readability and should not be present in the actual string):

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm:ss.sssssssss [time_zone_id] [u-ca=calendar_id] 

Different classes have different requirements for the presence of each component, so you will find a section titled "RFC 9557 format" in each class's documentation, which specifies the format recognized by that class.

This is very similar to the date time string format used by Date, which is also based on ISO 8601. The main addition is the ability to specify micro- and nanosecond components, and the ability to specify the time zone and calendar system.

Temporal.Duration

Represents a difference between two time points, which can be used in date/time arithmetic. It is fundamentally represented as a combination of years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds values.

Temporal.Instant

Represents a unique point in history, with nanosecond precision. It is fundamentally represented as the number of nanoseconds since the Unix epoch (midnight at the beginning of January 1, 1970, UTC), without any time zone or calendar system.

Temporal.Now

Provides methods for getting the current time in various formats.

Temporal.PlainDate

Represents a calendar date (a date without a time or time zone); for example, an event on a calendar which happens during the whole day no matter which time zone it's happening in. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system.

Temporal.PlainDateTime

Represents a date (calendar date) and time (wall-clock time) without a time zone. It is fundamentally represented as a combination of a date (with an associated calendar system) and a time.

Temporal.PlainMonthDay

Represents the month and day of a calendar date, without a year or time zone; for example, an event on a calendar that recurs every year and happens during the whole day. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The year is used to disambiguate the month-day in non-ISO calendar systems.

Temporal.PlainTime

Represents a time without a date or time zone; for example, a recurring event that happens at the same time every day. It is fundamentally represented as a combination of hour, minute, second, millisecond, microsecond, and nanosecond values.

Temporal.PlainYearMonth

Represents the year and month of a calendar date, without a day or time zone; for example, an event on a calendar that happens during the whole month. It is fundamentally represented as an ISO 8601 calendar date, with year, month, and day fields, and an associated calendar system. The day is used to disambiguate the year-month in non-ISO calendar systems.

Temporal.ZonedDateTime

Represents a date and time with a time zone. It is fundamentally represented as a combination of an instant, a time zone, and a calendar system.

Temporal[Symbol.toStringTag]

The initial value of the [Symbol.toStringTag] property is the string "Temporal". This property is used in Object.prototype.toString().