JS Temporal Date 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 legacy Date object, Temporal objects are immutable.
Methods like until(), add(), or with() 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 »
Temporal handles leap year adjustments automatically.
The width() Method
The width() method returns a new date with specific fields replaced.
Example
// Create a Temporal object
const date = Temporal.PlainDate.from("2026-05-17");
// Replace month and day
const customDate = date.with({ month:12, day:25 });
Try it Yourself »
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.
Summary
Temporal makes date arithmetic clear and predictable.
You can safely add or subtract time without mutating values or breaking across DST changes.
