JS Temporal Arithmetic
Add and Subtract Dates Safely
JavaScript Temporal has methods for easy and reliable date and time arithmetic.
Add and subtract days, months, years, and time without modifying the original value.
Perform date arithmetic without DST (Daylight Saving Time) or Time Zone problems.
Temporal add() and subtract()
All temporal objects have their own add() method:
- duration.add(duration)
- instant.add(duration)
- plaindate.add(duration)
- plaintime.add(duration)
- plainyearmonth.add(duration)
- plainmonthday.add(duration)
- plaindatetime.add(duration)
- zoneddatetime.add(duration)
All temporal objects have their own subtract() method:
- duration.subtract(duration)
- instant.subtract(duration)
- plaindate.subtract(duration)
- plaintime.subtract(duration)
- plainyearmonth.subtract(duration)
- plainmonthday.subtract(duration)
- plaindatetime.subtract(duration)
- zoneddatetime.subtract(duration)
JavaScript Temporal Add
The add() method accepts a duration object as input.
Example: { days: 10 }.
It returns a new temporal date object moved forward by the 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 »
JavaScript Temporal Subtract
The subtract() method accepts a duration object as input.
Example: { days: 10 }.
It returns a new temporal date object moved backward by the duration.
Syntax
temporal.subtract(duration)
Example
// Create a Temporal object
const myDate = Temporal.PlainDate.from("2026-05-17");
// Subtract a duration
const newDate = myDate.subtract({ days: 10 });
Try it Yourself »
Both add and subract are immutable: They both return a new Temporal object.
Date Boundaries
Both add and subtract handle date boundaries:
Adding one day to March 31st is April 1st.
Add Months
Temporal automatically handles different month lengths.
Example
// Create a Temporal object
const date = Temporal.PlainDate.from("2026-05-17");
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
// Create a Temporal object
const date = Temporal.PlainDate.from("2024-02-29");
const result = date.add({ years: 1 });
Try it Yourself »
Temporal handles leap year adjustments automatically.
Supported Duration Units
The add() and subtract()
methods accept a duration object as input.
Example: { months: 2, days: 7, hours: 1 }.
The following duration units are supported:
- years
- months
- weeks
- days
- hours
- minutes
- seconds
- milliseconds
- microseconds
- nanoseconds
Add Multiple Units
Example
// Create any Temporal object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Add multiple units
const newDate = myDate.add({ years: 1, months: 2, days: 15 });
Try it Yourself »
PlainDateTime add() and subtract()
You can safely add or subtract time.
The original value does not change.
Example
// Create a PlainDateTime object
const date = Temporal.PlainDateTime.from("2026-05-17T14:30:00");
// Add and subtract time
const earlier = dateTime.subtract({ minutes: 30 });
const later = dateTime.add({ hours: 2 });
Try it Yourself »
PlainDate add() and subtract()
Example
// Create a PlainDate object
const date = Temporal.PlainDate.from("2026-05-17");
// Add and subtract time
const earlier = date.subtract({ months: 3 });
const later = date.add({ days: 10 });
Try it Yourself »
Instant add() and subtract()
From a Temporal.Instant you can only add or subtract time durations (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 a Duration to Now
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });
Try it Yourself »
Immutable
Unlike the old Date object, Temporal objects are immutable.
All methods return a new instance without modifying the existing one.
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
The JavaScript Date object correctly implements leap year rules, but calendar calculations involving leap years can produce surprising results because invalid dates are automatically adjusted instead of reported as errors.
Adding one year to a leap day
// Create a Date object
let d = new Date("2024-02-29");
// Add one year
d.setFullYear(d.getFullYear() + 1);
Try it Yourself »
Many people would expect February 28, but Date silently moves the date to March 1.
Adding 365 days is not the same
// Create a Date object
let d = new Date("2024-02-29");
// Add one year
d.setDate(d.getDate() + 365);
Try it Yourself »
Now the result is February 28, which is different from setFullYear().
This illustrates that Date mixes calendar and day arithmetic in ways that can be surprising.
Invalid dates are silently corrected
// Create a Date object
let d = new Date(2025, 1, 29);
Try it Yourself »
Instead of reporting an invalid date, JavaScript quietly changes it into another valid date.
Temporal Overflow
Temporal lets you choose what should happen when a date becomes invalid.
For example: February 29, 2024 + 1 year becomes invalid, because 2025 has no February 29.
The overflow option controls what happens when a date calculation produces an invalid date.
With overflow: "constrain", Temporal changes the result to the nearest valid date.
With overflow: "reject", Temporal throws an error instead of changing the date.
Overflow Default
// Create a PlainDate object
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
const nextYear = d.add({ years: 1 });
Try it Yourself »
Oveflow: "constrain"
// Create a PlainDate object
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
const nextYear = d.add(
{ years: 1 },
{ overflow: "constrain" }
);
Try it Yourself »
Oveflow: "reject"
// Create a PlainDate object
const d = Temporal.PlainDate.from("2024-02-29");
// Add one year
try {
const nextYear = d.add(
{ years: 1 },
{ overflow: "reject" }
);
text = nextYear.toString();
} catch (err) {
text = err.name;
}
Try it Yourself »
With Temporal, you can explicitly choose the overflow behavior.
Best Practices
Use PlainDate for date-only arithmetic.
Use ZonedDateTime for time zone-aware calculations.
Avoid manual millisecond calculations.
Prefer Temporal because it is Immutable.
