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 accepts a duration object as input.
Example: { days: 10 } .
It returns a new temporal object moved forward by the duration.
temporal .add( duration )JavaScript Temporal Subtract
The subtract() method accepts a duration object as input.
Example: { days: 10 } .
It returns a new temporal object moved backward by the duration.
temporal .subtract( duration )Both methods are immutable , returning new Temporal objects.
Date Boundaries
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 });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 });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 });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 });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 });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 });Add a Duration to Now
Example
// Create a Temporal object
const today = Temporal.Now.plainDateISO();
// Add a duration
const nextWeek = today.add({ days: 7 });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 });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);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.