JavaScript Temporal Duration
The Temporal.Duration Object
The Temporal.Duration object represents a length of time like 7 days and 1 hour.
The Temporal.Duration object includes these properties:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- nanoseconds
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
Temporal Duration Formats
A Duration object can be parsed as a string using the ISO 8601 duration format.
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".
| Code | Description |
|---|---|
| + | Optional +/- sign for 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
Create a Duration Using from()
You can create a Duration using 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 a Duration
You can add a Duration to a date using the subtract() method.
The original value does not change.
Example
const date = Temporal.PlainDate.from("2026-05-17");
const duration = Temporal.Duration.from({ days: 10 });
const result = date.add(duration);
Try it Yourself »
Subtract a Duration
You can subtract a Duration using the subtract() method.
Example
const date = Temporal.PlainDate.from("2026-05-17");
const duration = Temporal.Duration.from({ days: 10 });
const result = date.subtract(duration);
Try it Yourself »
Calculate Temporal Differences
You calculate the differnce between two temporal dates using until() or since().
The since() method is effectively the inverse of the
until() method.
Or the until() method is the inverse of the
since() method.
JavaScript Temporal since()
The since() method calculates the duration between two temporal dates.
Syntax
t1.since(t2, options)
Meaning:
At time t1, how much time has passed since time t2?
Example: Plain Date
const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-17");
const duration = end.since(start);
Try it Yourself »
Example: Plain Time
const start = Temporal.PlainTime.from("09:00");
const end = Temporal.PlainTime.from("17:30");
const duration = end.since(start);
Try it Yourself »
Example: ZonedDateTime
const start = Temporal.ZonedDateTime.from(
"2026-02-17T09:00:00+01:00[Europe/Oslo]");
const end = Temporal.ZonedDateTime.from(
"2026-02-17T17:30:00+01:00[Europe/Oslo]");
const duration = end.since(start);
Try it Yourself »
Note
The since() method returns a Temporal.Duration Object
representing the elapsed time.
The duration is positive if the "other" date is in the past.
The duration is negative if the "other" date is in the future.
The Options Parameters
Example
const wedding = Temporal.PlainDate.from('2000-05-17');
const today = Temporal.Now.plainDateISO();
const duration = today.since(wedding);
Try it Yourself »
The since() method returns the total number of days,
but you can use the largestUnit option to break it down into years and months:
Example
const wedding = Temporal.PlainDate.from('2026-05-17');
const today = Temporal.Now.plainDateISO();
const duration = today.since(wedding, {largestUnit:'years'});
Try it Yourself »
JavaScript Temporal until()
The until() method calculates the duration between two temporal dates.
The until() method is effectively the inverse of the
since() method.
Syntax
t1.until(t2, options)
Meaning:
At time t1, how much time is it until t2?"
Example
Return a Duration representing the time between two dates:
const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-17");
const duration = start.until(end);
Try it Yourself »
Temporal since() vs until()
The methods are opposites.
| Method | Meaning |
|---|---|
| a.since(b) | time from b → a |
| a.until(b) | time from a → b |
Example
const start = Temporal.PlainDate.from("2026-05-01");
const end = Temporal.PlainDate.from("2026-05-17");
const duration1 = end.since(start);
const duration2 = start.until(end);
Try it Yourself »
Both return the same duration.
Think:
- since = past
- Until = future
Examples:
- since yesterday
- until tomorrow
The Compare() Method
Example
const duration1 = Temporal.Duration.from({ hours: 1, minutes: 30 });
const duration2 = Temporal.Duration.from({ minutes: 90 });
let text = "The durations are not equal.";
// Compare the durations
if (Temporal.Duration.compare(duration1, duration2) === 0) {
let text = "The durations are equal.";
}
Try it Yourself »
Note
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 and calendar math.
Instead, equality is checked using the static Temporal.Duration.compare() method.
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. - ISO 8601 Compatibility
Durations can be created from and converted to ISO 8601 duration strings (e.g., P3D for "3 days"). - 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
Adding or subtracting time.
Calculating age.
Measuring differences between dates.
Working with time spans (hours, days, months).
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) |
