JS Temporal.ZonedDateTime
Handle Time Zones Correctly
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
Note
A Temporal.ZonedDateTime represents a date and time with a time zone.
It is the safest way to handle international date and time calculations.
Why ZonedDateTime Is Important
Time zones and daylight saving time (DST) can cause serious bugs when using Date.
ZonedDateTime solves this by always storing the time zone together with the date and time.
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.
Create a ZonedDateTime
Example: December 7th, 1995 at 3:24 AM in US Pacific time (in Gregorian calendar).
Example
const zonedDate = Temporal.ZonedDateTime.from({
timeZone: 'America/Los_Angeles',
year: 1995,
month: 12,
day: 7,
hour: 3,
minute: 24,
second: 30,
millisecond: 0,
microsecond: 3,
nanosecond: 500
});
Try it Yourself »
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+01:00[Europe/Oslo]");
Try it Yourself »
Note
The time zone name is written inside square brackets.
Get Current Date and Time with Time Zone
Use Temporal.Now.zonedDateTimeISO() to get the current date and time with your system's time zone.
Example
const now = Temporal.Now.zonedDateTimeISO();
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");
Try it Yourself »
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 Date.
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 });
Try it Yourself »
Note
Temporal adjusts automatically if a DST change happens.
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");
Try it Yourself »
When to Use ZonedDateTime
International applications.
Booking systems.
Flight or travel systems.
Applications that must handle DST correctly.
Any system where time zones matter.
ZonedDateTime vs PlainDateTime
| Type | Includes Time Zone | Use Case |
|---|---|---|
PlainDateTime |
No | Local scheduling without conversion |
ZonedDateTime |
Yes | International or DST-aware systems |
Summary
Temporal.ZonedDateTime is the safest way to handle date and time with time zones.
It prevents common DST bugs and makes time zone conversions clear and predictable.
