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.
Example
// Create a duration using an object literal
const duration = Temporal.Duration.from({days:7, hours:2});
Try it Yourself »
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 |
Learn More:
Create a Duration Using the Constructor
You can create a Temporal.Duration object using the new constructor with integer parameters.
Example
Create a duration of 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.
Example
//Create a Duration
const duration = new Temporal.Duration(0, 0, 0, 7, 2, 0);
// List the Properties
let text =
"blank: " + duration.blank + " " +
"sign: " + duration.sign + " " +
"years: " + duration.years + " " +
"months: " + duration.months + " " +
"weeks: " + duration.weeks + " " +
"days: " + duration.days + " " +
"hour: " + duration.hours + " " +
"minutes: " + duration.minutes + " " +
"seconds: " + duration.seconds + " " +
"milliseconds: " + duration.milliseconds + " " +
"microseconds: " + duration.microseconds + " " +
"nanoseconds: " + duration.nanoseconds;
Try it Yourself »
Create a Duration Using from()
You can create a duration with the from() method with an
object literal like {days:7, hours: 2}:
Note
An object literal is a concise way to create an object in JavaScript by literally writing its contents as a set of key:value pairs enclosed in curly braces ( { } ).
This is the most common and efficient method for creating single, standalone JavaScript objects.
You can create a Duration using the from() method with an
ISO 8601 duration string:
Safe Date Arithmetic
the Temporal.Duration object facilitates safe and clear date and time arithmetic, preventing issues related to daylight saving time and time zone changes.
The Temporal.Duration object can handle time in various units, including years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds.
The Temporal.Duration object makes date arithmetic clear, readable, and safer than using manual millisecond calculations.
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
// Create a Duration
const d1 = Temporal.Duration.from({ hours:2, minutes:30 });
// Add a Duration
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
// Create a Duration
const d1 = Temporal.Duration.from({ hours:2, minutes:30 });
// Subtract a Duration
const d2 = d1.subtract({ hours:1, minutes:30 });
Try it Yourself »
Immutability
Temporal objects are immutable, meaning operations like add() or subtract() return a new Temporal.Duration instance, leaving the original unchanged.
Temporal add() and subtract() Methods
All temporal date objects have their own 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
// Create a PlainDate object
const date = Temporal.PlainDate.from("2026-05-17");
// Add a Duration
const duration = Temporal.Duration.from({ days: 10 });
const result = date.add(duration);
Try it Yourself »
// Create a PlainDate object
const date = Temporal.PlainDate.from("2026-05-17");
// Subtract a Duration
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 handeling 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 returns a new duration
with specific time units replaced (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 JavaScript 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 JavaScript Date methods.
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 |
|---|---|
| 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 |
Example
//Create a Duration
const duration = new Temporal.Duration(0, 0, 0, 7, 2, 0);
// List the Properties
let text =
"blank: " + duration.blank + " " +
"sign: " + duration.sign + " " +
"years: " + duration.years + " " +
"months: " + duration.months + " " +
"weeks: " + duration.weeks + " " +
"days: " + duration.days + " " +
"hour: " + duration.hours + " " +
"minutes: " + duration.minutes + " " +
"seconds: " + duration.seconds + " " +
"milliseconds: " + duration.milliseconds + " " +
"microseconds: " + duration.microseconds + " " +
"nanoseconds: " + duration.nanoseconds;
Try it Yourself »
