JS Temporal Arithmetic
Add and Subtract Dates Safely
The Temporal API provides 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 bugs and 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 accept a duration object as input.
Example: { days: 10 }.
It returns a new temporal 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 accept a duration object as input.
Example: { days: 10 }.
It returns a new temporal 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 methods are immutable, returning new Temporal objects.
Date Boundaries
Add and subtract handles 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-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
// 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 »
Instand 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
JavaScript legacy Date can cause leap year errors:
Example
// Create a Date object
const start = new Date("2026-02-17");
// Add 12 days
start.setDate(start.getDate() + 12);
Result:
2026-02-29
Try it Yourself »
The Result is Wrong!
2026 is not a leap year.
2026 is not divisible by 4.
The closest leap years are 2024 and 2028.
Best Practices
Use PlainDate for date-only arithmetic.
Use ZonedDateTime for time zone-aware calculations.
Avoid manual millisecond calculations.
Prefer immutable operations.
