JS Temporal Arithmetic
Add and Subtract Dates Safely
The Temporal API provides methods for easy and reliable date and time arithmetic.
Learn how to add and subtract dates safely using JavaScript Temporal.
Perform date arithmetic without DST bugs or mutation problems.
Note
Temporal provides safe and clear methods for date arithmetic.
You can add or subtract days, months, years, and more without modifying the original value.
Add Days
Use the add() method to add days.
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Add a duration
const newDate = myDate.add({ days: 7 });
Try it Yourself »
The original date is not changed.
Subtract Days
Use subtract() to subtract time.
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Subtract a duration
const newDate = myDate.subtract({ days: 7 });
Try it Yourself »
JavaScript Temporal add()
The add() method returns a new date moved forward by a given duration.
Syntax
temporal.add(duration)
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Add a duration
const newDate = myDate.add({ days: 10 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add multiple units
const newDate = today.add({ years: 1, months: 2, days: 15 });
Try it Yourself »
Supported Units
You can add or subtract various time units using a duration object:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- microseconds
- nanoseconds
Note
Unlike the old Date object, Temporal objects are immutable.
Methods like add(), subtract() or until() always return a new instance rather than modifying the existing one.
Temporal Add and Subtract
Both methods are immutable, returning new Temporal objects.
Both methods accept an object with duration properties { days: 7, hours: 1 } as input.
Both methods handles date boundaries: adding one day to March 31st is April 1st.
JavaScript Temporal subtract()
The subtract() method returns a new temporal object representing this date moved backward
by a given duration.
Syntax
temporal.subtract(duration)
From a Temporal.PlainDate (a date without a time zone) you can subtract a full duration:
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Subtract a duration
const newDate = myDate.subtract({ days: 7 });
Try it Yourself »
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Subtract a duration
const lastWeek = today.subtract({ days: 7 });
Try it Yourself »
From a Temporal.Instant you can only subtract a fixed duration (hours, minutes, seconds) but not calendar durations like months or years, as their length can vary depending on the time zone and the calendar.
Example
// Create a Temporal.Instant object
const now = Temporal.Instant.fromEpochMilliseconds(Date.now());
// Subtract 5 hours and 30 minutes
const fiveHalfHoursAgo = now.subtract({ hours: 5, minutes: 30 });
Try it Yourself »
Add Months
Temporal automatically handles different month lengths.
Example
const date = Temporal.PlainDate.from("2026-01-31");
const result = date.add({ months: 1 });
Try it Yourself »
If the next month has fewer days, Temporal adjusts automatically.
Add Years
Adding years works correctly, even for leap years.
Example
const date = Temporal.PlainDate.from("2024-02-29");
const result = date.add({ years: 1 });
Try it Yourself »
Note
Temporal handles leap year adjustments automatically.
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 »
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
The compare() method returns -1 if the first date is earlier, 1 if it is later, and 0 if they are equal:
Example
// Create two Temporal objects
const date1 = Temporal.PlainDate.from("2026-05-17");
const date2 = Temporal.PlainDate.from("2024-12-25");
// Compare the dates
result = Temporal.PlainDate.compare(date1, date2);
Try it Yourself »
The compare() method is designed to be passed directly into the JavaScript Array.sort() method:
Example
// Create an Array of dates
const dates = [
Temporal.PlainDate.from("2026-05-17"),
Temporal.PlainDate.from("2022-01-01"),
Temporal.PlainDate.from("2024-12-25")
];
// Sort chronologically
dates.sort(Temporal.PlainDate.compare);
Try it Yourself »
Date Comparison
Always use the equals() or compare() methods rather than standard equality operators.
The equals() Method
Example
// Create two Temporal objects
const date1 = Temporal.PlainDate.from('2026-05-17');
const date2 = Temporal.PlainDate.from('2026-05-17');
let result = date1.equals(date2);
Try it Yourself »
Date Arithmetic with ZonedDateTime
ZonedDateTime handles daylight saving time (DST) safely.
Example
const start = Temporal.ZonedDateTime.from
("2026-03-29T00:00:00+01:00[Europe/Oslo]");
const nextDay = start.add({ days: 1 });
Try it Yourself »
If a DST change occurs, Temporal adjusts automatically.
Compare with Date Arithmetic
Date modifies the original object and may cause DST-related issues.
Date Example
const start = new Date("2026-02-17");
start.setDate(start.getDate() + 10);
Try it Yourself »
Best Practices
Use
PlainDatefor date-only arithmetic.Use
ZonedDateTimefor time zone-aware calculations.Avoid manual millisecond calculations.
Prefer immutable operations.
