JavaScript Temporal API

The JavaScript Temporal API gives you a modern way to work with dates and times. It separates calendar dates, clock times, time zones, instants, and durations into different objects, so your code says exactly what kind of time value it is handling.

The older Date object stores a single timestamp and often mixes local time, UTC, parsing, and mutation in confusing ways. Temporal is designed to reduce those mistakes and make date logic easier to read.

Why Temporal Is Useful

You should use Temporal when your program needs clear date calculations, reliable time zone handling, or immutable date-time values. It is helpful for bookings, renewals, reminders, reports, and schedules.

Temporal Type Use
Temporal.PlainDate A calendar date without time or time zone
Temporal.PlainTime A clock time without a date
Temporal.PlainDateTime A date and time without a time zone
Temporal.ZonedDateTime A date and time in a named time zone
Temporal.Duration A length of time such as days, hours, or minutes
Temporal.Instant An exact point on the global timeline

Create a Plain Date

Use Temporal.PlainDate when you only need a calendar date. Birthdays, due dates, course dates, and subscription start dates are common examples.

Example:

// Create a date without time or time zone.
const joiningDate = Temporal.PlainDate.from("2026-09-15");

console.log(joiningDate.toString());
console.log(joiningDate.dayOfWeek);

Add or Subtract Time

Temporal objects are immutable. Methods such as add() return a new value and do not change the original object.

Example:

const trialStart = Temporal.PlainDate.from("2026-09-01");

// Add 14 days and keep the original date unchanged.
const trialEnd = trialStart.add({ days: 14 });

console.log(trialStart.toString());
console.log(trialEnd.toString());

Work with Time Zones

Use Temporal.ZonedDateTime when a date and time must belong to a real time zone. This is important for meetings, reminders, and deadlines that depend on a city or region.

Example:

// Store a meeting in the Asia/Kolkata time zone.
const meeting = Temporal.ZonedDateTime.from({
  year: 2026,
  month: 9,
  day: 20,
  hour: 10,
  minute: 30,
  timeZone: "Asia/Kolkata"
});

console.log(meeting.toString());

Compare Dates

Use Temporal.PlainDate.compare() when you need sorting or direct comparison. It returns a negative number, zero, or a positive number.

Example:

const firstDate = Temporal.PlainDate.from("2026-10-01");
const secondDate = Temporal.PlainDate.from("2026-09-25");

// Sort dates from earliest to latest.
const dates = [firstDate, secondDate].sort(Temporal.PlainDate.compare);

console.log(dates.map(date => date.toString()));

Calculate the Difference Between Dates

The until() and since() methods create a duration between two Temporal values. Choose the largest unit you want in the result.

Example:

const start = Temporal.PlainDate.from("2026-09-05");
const end = Temporal.PlainDate.from("2026-10-10");

// Find the calendar difference in days.
const duration = start.until(end, { largestUnit: "day" });

console.log(duration.days);

Runnable Browser Example

The following example checks whether the current browser supports Temporal, then calculates a renewal date from a plain calendar date.

Example:

<!DOCTYPE html>
<html>
<body>
  <div id="output"></div>

  <script>
    const output = document.querySelector("#output");

    if ("Temporal" in window) {
      // PlainDate stores a date without a time zone.
      const startDate = Temporal.PlainDate.from("2026-09-05");
      const renewalDate = startDate.add({ months: 1 });
      output.textContent = renewalDate.toString();
    } else {
      output.textContent = "Temporal is not available in this browser yet.";
    }
  </script>
</body>
</html>

Practical Guidelines

  • Use PlainDate for dates that do not need a time zone.
  • Use ZonedDateTime when the time zone affects the result.
  • Keep Date only when you need compatibility with older APIs.
  • Check browser support before using Temporal directly in public pages.
  • Use a polyfill only when your project requires support before all target browsers include Temporal.

Tip: Do not use Date and Temporal interchangeably in the same calculation. Convert at clear boundaries so your code remains predictable.

Conclusion

JavaScript Temporal makes date and time code clearer by giving each kind of time value its own object. Use it for calendar dates, durations, time zones, and exact instants when you need readable and reliable time handling.

Found This Page Useful? Share It!
Get the Latest Tutorials and Updates
Join us on Telegram