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
const duration = new Temporal.Duration(0, 0, 0, 7);
The parameters represent:
Years
Months
Weeks
Days
Hours
Minutes
Seconds
Milliseconds
Microseconds
Nanoseconds
In this example, the duration is 7 days.
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().
Example
const start = Temporal.PlainDate.from("2026-02-01");
const end = Temporal.PlainDate.from("2026-02-17");
const difference = start.until(end);
This returns a Duration representing the time between the two dates.
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.
Next chapter: JavaScript Temporal Date Arithmetic.
