JavaScript Temporal.Duration
Add and Subtract Time
What You Will Learn:
- How to use JavaScript Temporal.Duration
- How to to represent and calculate lengths of time
- Add and subtract days, hours, months, and more safely
Note
A Temporal.Duration represents a length of time.
It can include years, months, weeks, days, hours, minutes, seconds, and more.
Create a Duration
You can create a Duration using numeric values.
Example
In this example, the duration is 7 days.
const duration = new Temporal.Duration(0, 0, 0, 7);
Try it Yourself »
The parameters represent:
- Years
- Months
- Weeks
- Days
- Hours
- Minutes
- Seconds
- Milliseconds
- Microseconds
- Nanoseconds
Create Duration from an Object
You can also create a Duration using an object.
Example
const duration = Temporal.Duration.from({ days: 7, hours: 2 });
Add a Duration
You can add a Duration to a date or date-time.
The original value does not change.
Example
const date = Temporal.PlainDate.from("2026-02-17");
const duration = Temporal.Duration.from({ days: 7 });
const result = date.add(duration);
Subtract a Duration
You can subtract a Duration using the subtract() method.
Example
const date = Temporal.PlainDate.from("2026-02-17");
const duration = Temporal.Duration.from({ days: 7 });
const result = date.subtract(duration);
console.log(result);
Calculate the Difference Between Two Dates
You can calculate the duration between two dates using until() or since().
Duration objects can be parsed as a string using the ISO 8601 duration format.
It has the following form (spaces are only 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 |
JavaScript Temporal since()
The since() method calculates the duration between
two temporal date/time values.
The since() method is effectively the inverse of the
until() method.
Syntax
temporal.since(temporal, options)
The since() method returns a Temporal.Duration Object
representing the elapsed time.
The duration is positive if the "other" date is in the past, or negative if it is in the future:
Example
const wedding = Temporal.PlainDate.from('2026-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 date/time values.
The until() method is effectively the inverse of the
since() method.
Syntax
temporal.until(temporal, options)
Examples
Return a Duration representing the time between 2026-05-17 and now:
const wedding = Temporal.PlainDate.from('2026-05-17');
const today = Temporal.Now.plainDateISO();
const duration = today.until(wedding);
Try it Yourself »
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 difference = start.until(end);
Try it Yourself »
Note
The since() method does this - other.
The until() method does other - this.
Duration vs Date Math
With Date, you often calculate time differences manually using milliseconds.
Date Example
const start = new Date("2026-02-01");
const end = new Date("2026-02-17");
const diff = end - start;
Temporal provides built-in methods that are clearer and safer.
When to Use Duration
Adding or subtracting time.
Calculating age.
Measuring differences between dates.
Working with time spans (hours, days, months).
Summary
Temporal.Duration represents a length of time.
It makes date arithmetic clear, readable, and safer than using manual millisecond calculations.
