Temporal API: Finally, Proper Date and Time in JavaScript
Learn the Temporal API — the modern replacement for Date that handles time zones, calendars, and duration correctly.
Why Temporal?
The JavaScript \Date\ object is famously broken: mutable, no time zone support, confusing month indexing (0-11), poor parsing, and no duration concept. Libraries like Moment.js and date-fns filled the gap, but the Temporal API is the official fix — a complete, immutable, time-zone-aware date/time API built into the language.
Core Temporal Types
Temporal introduces several types for different use cases:
``javascript
// Plain types — no time zone
const date = Temporal.PlainDate.from('2026-04-05');
const time = Temporal.PlainTime.from('14:30:00');
const dateTime = Temporal.PlainDateTime.from('2026-04-05T14:30:00');
// Zoned — with time zone const zoned = Temporal.ZonedDateTime.from({ year: 2026, month: 4, day: 5, hour: 14, minute: 30, timeZone: 'Asia/Seoul' });
console.log(zoned.toString()); // "2026-04-05T14:30:00+09:00[Asia/Seoul]"
// Instant — absolute point in time (like Unix timestamp)
const now = Temporal.Now.instant();
console.log(now.epochMilliseconds);
`
Working with Durations
Temporal has first-class duration support — something Date never had.
`javascript
const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
const meeting = Temporal.PlainDateTime.from('2026-04-05T09:00:00');
const end = meeting.add(duration); console.log(end.toString()); // "2026-04-05T11:30:00"
// Duration between two dates
const start = Temporal.PlainDate.from('2026-01-01');
const finish = Temporal.PlainDate.from('2026-04-05');
const diff = start.until(finish, { largestUnit: 'month' });
console.log(diff.toString()); // "P3M4D" (3 months, 4 days)
`
Time Zone Conversions
Converting between time zones is simple and correct — no more manual offset math.
`javascript
const seoulTime = Temporal.ZonedDateTime.from({
year: 2026, month: 4, day: 5,
hour: 14, minute: 0,
timeZone: 'Asia/Seoul'
});
const nyTime = seoulTime.withTimeZone('America/New_York'); console.log(nyTime.toString()); // "2026-04-05T01:00:00-04:00[America/New_York]"
const londonTime = seoulTime.withTimeZone('Europe/London');
console.log(londonTime.toString());
// "2026-04-05T06:00:00+01:00[Europe/London]"
`
Comparison and Sorting
All Temporal types support proper comparison via static \compare\ methods.
`javascript
const dates = [
Temporal.PlainDate.from('2026-12-25'),
Temporal.PlainDate.from('2026-01-01'),
Temporal.PlainDate.from('2026-07-04'),
];
dates.sort(Temporal.PlainDate.compare); console.log(dates.map(d => d.toString())); // ["2026-01-01", "2026-07-04", "2026-12-25"] ``
Temporal is the most significant improvement to JavaScript's standard library in years. Start using it today to write date/time code that is correct, readable, and time-zone-safe by default.