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 Time Zone problems.
JavaScript Temporal Add and Subtract
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.
Both methods are immutable, returning new Temporal objects.
The add() method returns a temporal object moved forward by a given duration.
Syntax
temporal.add(duration)
The subtract() method returns a temporal object moved backward
by a given duration.
Syntax
temporal.subtract(duration)
Add Days to a PlainDate
Use the add() method to add days.
Example
// Create a PlainDate 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 from a PlainDate
Use subtract() to subtract time.
Example
// Create a PlainDate object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Subtract a duration
const newDate = myDate.subtract({ days: 7 });
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
Add Multiple Units
Example
// Create a PlainDate object
const myDate = Temporal.PlainDate.from('2026-05-17');
// Add multiple units
const newDate = today.add({ years: 1, months: 2, days: 15 });
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 »
Temporal handles leap year adjustments automatically.
Add a Duration to an Istant
From a Temporal.Instant you can only add or 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 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 »
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.
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 »
2026 is not a leap year.
2026 is not divisible by 4.
The closest leap years are 2024 and 2028.
Best Practices
Use
PlainDatefor date-only arithmetic.Use
ZonedDateTimefor time zone-aware calculations.Avoid manual millisecond calculations.
Prefer immutable operations.
