JavaScript Temporal Duration
The Temporal.Duration Object
The Temporal.Duration object represents a length of time.
Example: 7 days and 1 hour.
The Temporal.Duration object includes these properties:
years, months, weeks, days, hours, minutes, seconds, milliseconds, and nanoseconds.
ISO 8601 Compatibility
Durations can be created from and converted to ISO 8601 duration strings (e.g."P7DT2H").
It has the following form (spaces are added for readability):
+P nY nM nW nD T nH nM nS
For example, "P3Y6M4DT12H30M5S" represents a duration of "three years, six months, four days, twelve hours, thirty minutes, and five seconds".
Temporal Duration Format Codes
| Code | Description |
|---|---|
| ± | Optional positive/negative duration (default is +). |
| P | Duration designator (for period) |
| nY | Number of calendar years |
| nM | Number of calendar months |
| nW | Number of weeks |
| nD | Number of calendar days |
| T | Time designator (precedes time components) |
| nH | Number of hours |
| nM | Number of minutes |
| nS | Number of seconds |
Create a Duration Using the Constructor
You can create a Duration using using the new constructor with integer parameters.
Example
In this example, the duration is 7 days and 2 hours.
const duration = new Temporal.Duration(0, 0, 0, 7, 2);
Try it Yourself »
The parameters represent:
- Years
- Months
- Weeks
- Days
- Hours
- Minutes
- Seconds
- Milliseconds
- Microseconds
- Nanoseconds
Temporal.Duration Properties
The Temporal.Duration object has 12 properties of time information.
Create a Duration Using from()
You can create a duration with the from() method with an object like
{days:7, hours: 2}:
You can create a Duration using the from() method with an ISO 8601 string:
Add and Subtract Time
The Temporal.Duration object makes date arithmetic clear, readable, and safer than using manual millisecond calculations.
- How to use JavaScript Temporal.Duration
- How to to represent and calculate lengths of time
- Add and subtract days, hours, months, and more safely
The Temporal Duration add() Method
The add() method returns a new duration with a duration added.
The add() method does not change the original duration.
Example
const d1 = Temporal.Duration.from({ hours:2, minutes:30 });
const d2 = d1.add({ hours:1, minutes:30 });
Try it Yourself »
The Temporal Duration subtract() Method
The subtract() method returns a new duration with a duration subtracted.
The subtract() method does not change the original duration.
Example
const d1 = Temporal.Duration.from({ hours:2, minutes:30 });
const d2 = d1.subtract({ hours:1, minutes:30 });
Try it Yourself »
Temporal add() and subtract() Methods
All temporal date objects have add() and subtract methods
- Instant.add(duration)
- PlainDate.add(duration)
- PlainTime.add(duration)
- PlainYearMonth.add(duration)
- PlainMonthDay.add(duration)
- PlainDateTime.add(duration)
- ZonedDateTime.add(duration)
- Instant.subtract(duration)
- PlainDate.subtract(duration)
- PlainTime.subtract(duration)
- PlainYearMonth.subtract(duration)
- PlainMonthDay.subtract(duration)
- PlainDateTime.subtract(duration)
- ZonedDateTime.subtract(duration)
Examples
const date = Temporal.PlainDate.from("2026-05-17");
const duration = Temporal.Duration.from({ days: 10 });
const result = date.add(duration);
Try it Yourself »
const date = Temporal.PlainDate.from("2026-05-17");
const duration = Temporal.Duration.from({ days: 10 });
const result = date.subtract(duration);
Try it Yourself »
The Compare() Method
The Temporal.Duration object does not have an equals() method due to the complexity of duration equality,
specifically how to handle different representations of the same duration.
Instead, equality is checked using the static Temporal.Duration.compare() method.
This method returns -1 if the first duration is shorter, 0 if it is the same, and 1 if it is longer.
Examples
// Create two Durations
const d1 = Temporal.Duration.from({ hours:1, minutes:30 });
const d2 = Temporal.Duration.from({ minutes:90 });
// Compare the Durations
let result = Temporal.Duration.compare(d1, d2);
Try it Yourself »
// Create two Durations
const d1 = Temporal.Duration.from({ hours:1, minutes:30 });
const d2 = Temporal.Duration.from({ hours:1, minutes:30 });
// Compare the Durations
let result = Temporal.Duration.compare(d1, d2);
Try it Yourself »
Note
Note that the two examples above both return 0.
The width() Method
The width() method creates a new duration
with modified time units (years, months, days, etc).
Example
// Create a Duration
const duration = Temporal.Duration.from({hours:10, minutes:30});
// Create a new duration with the minutes changed to 45
const newDuration = duration.with({minutes:45});
Try it Yourself »
Duration vs Date Math
With Date, you must often calculate time differences
manually using milliseconds.
Date Example
const start = new Date("2026-05-01");
const end = new Date("2026-05-17");
const diff = end - start;
Try it Yourself »
Note
Temporal provides methods that are clearer and safer than using Date methods.
Key Features of Temporal.Duration
- Precise Representation
A Temporal.Duration object can handle time in various units, including years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. - Safe Date Arithmetic
Temporal.Duration facilitates safe and clear date and time arithmetic, preventing issues related to daylight saving time and time zone changes. Adding or subtracting time.
Calculating age.
Measuring differences between dates.
Working with time spans (hours, days, months).
Immutability
Temporal objects are immutable, meaning operations like add() or subtract() return a new Temporal.Duration instance, leaving the original unchanged.
When to Use Duration
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 |
