Temporal ZonedDate

Handle Time Zones Correctly

The Temporal.ZonedDateTime object represents a date and time with a time zone.

It is the safest way to handle international date and time calculations.

It prevents common DST bugs and makes time zone conversions clear and predictable.

What You Will Learn:

• How to use JavaScript Temporal.ZonedDateTime
• How to handle time zones correctly
• How to add and subtract date
• How to avoid DST (Daylight Saving Time) bugs
• How to convert between time zones safely

Why ZonedDateTime Is Important

Time zones and daylight saving time (DST) can cause serious bugs when using JavaScript Date.

ZonedDateTime solves this by always storing the time zone together with the date and time.

A Temporal.ZonedDateTime is a timezone and calendar-aware date/time object that represents a real time event from the perspective of a particular region on Earth.

The Temporal.ZonedDateTime object is optimized for cases that require a time zone, DST-safe arithmetic and interoperability with an RFC 5545 calendar.

Example: December 7th, 1995 at 3:24 AM in US Pacific time (in Gregorian calendar).

Create a ZonedDateTime

Example

const zonedDate = Temporal.ZonedDateTime.from({

  timeZone: 'Europe/Oslo',

  year: 2026,

  month: 5,

  day: 17,

  hour: 14,

  minute: 30,

  second: 0,

  millisecond: 0,

  microsecond: 0,

  nanosecond: 500

});

You can also create a ZonedDateTime from a string that includes a time zone.

Example

const zdt = Temporal.ZonedDateTime.from

("2026-02-17T14:30:00[Europe/Oslo]");

Note: The time zone name is written inside square brackets.

Get Current Date and Time with Time Zone

The Temporal.Now.zonedDateTimeISO() method returns your system's current date, time, and time zone as a Temporal.ZonedDateTime object.

Example

const now = Temporal.Now.zonedDateTimeISO();

Note: The current time is returned in ISO 8601 format.

The ISO 8601 Format

• 2026-03-02: The calendar date (Year-Month-Day).
• T10:36:00: The time of day (T-Hour:Minute:Second).
• +01:00: The offset from UTC (Coordinated Universal Time).
• [Europe/Oslo]: The IANA time zone name, which is the system's local time zone in this case.

Convert Between Time Zones

You can convert a ZonedDateTime to another time zone.

Example

const oslo = Temporal.ZonedDateTime.from

("2026-05-17T14:30:00+01:00[Europe/Oslo]");

const newYork = oslo.withTimeZone("America/New_York");

Note: The exact moment stays the same, but the local clock time changes.

Add Time Safely (DST Safe)

Adding days across a daylight saving change can break with Javascript Date.

Temporal.ZonedDateTime handles this correctly.

Example

const start = Temporal.ZonedDateTime.from

("2026-03-29T00:00:00+01:00[Europe/Oslo]");

const nextDay = start.add({ days: 1 });

Note: Temporal adjusts automatically if a DST change happens.

ZonedDateTime since()

The since() method calculates the duration between two temporal dates.

Example

const start = Temporal.ZonedDateTime.from(

"2026-02-17T09:00:00+01:00[Europe/Oslo]");

const end = Temporal.ZonedDateTime.from(

"2026-02-17T17:30:00+01:00[Europe/Oslo]");

const duration = end.since(start);

JavaScript since() and until()

All temporal date objects have their own since() method:

• plaindate.since(plaindate)
• plaintime.since(plaintime)
• plainyearmonth.since(plainyearmonth)
• plainmonthday.since(plainmonthday)
• plaindatetime.since(plaindatetime)
• zoneddatetime.since(zoneddatetime)
• instant.since(instant)

All temporal objects have their own until() method:

• plaindate.until(plaindate)
• plaintime.until(plaintime)
• plainyearmonth.until(plainyearmonth)
• plainmonthday.until(plainmonthday)
• plaindatetime.until(plaindatetime)
• zoneddatetime.until(zoneddatetime)
• instant.until(instant)

Note: LearnMore: JavaScript Temporal Since and Until

The with() Method

The with() method creates a new zoned date-time with specified field(s) replaced.

Example

// Create a ZonedDateTime

const date = Temporal.ZonedDateTimr.from("2026-05-17T14:30:00[Europe/Oslo]");

// Replace month and day

const customDate = date.with({ month:12, day:25 });

Convert from Instant

An Instant represents a UTC moment.

You can convert it to a ZonedDateTime in a specific time zone.

Example

const instant = Temporal.Now.instant();

const zoned = instant.toZonedDateTimeISO("Europe/Oslo");

ZonedDateTime vs PlainDateTime

When to Use ZonedDateTime

• International applications.
• Booking systems.
• Flight or travel systems.
• Applications that must handle DST correctly.
• Any system where time zones matter.

Temporal ZonedDateTime Methods

Temporal ZonedDateTime Properties

Display All Properties

const zoned = Temporal.ZonedDateTime.from("2026-05-17T14:30:00[Europe/Oslo]");