Date
One old mutable object for many date-time tasks.
Platform under construction
Temporal vs Date
Date and Temporal solve overlapping problems, but their mental models are very different. Date is old and universal; Temporal is clearer and more precise.
const date = new Date("2026-01-01T09:30:00Z");
if ("Temporal" in globalThis) {
const plain = Temporal.PlainDate.from("2026-01-01");
}
Dates, Time & Intl
Use Date carefully today and learn Temporal for clearer future code.
Date is available everywhere and still matters. It represents an instant, but it also exposes many local and UTC component methods on one mutable object.
Temporal separates concepts into types. A plain calendar date is not the same thing as an exact instant. A wall-clock time is not the same thing as a zoned date-time.
The practical path is simple: understand Date because production code still uses it, and learn Temporal because it explains date-time modeling much more clearly.
Temporal
Modern namespace with specific types for specific concepts.
Support
Date is universal. Temporal needs support checks in current production work.
Mental model
Temporal teaches clearer thinking about time.
Examples
Make the date-time concept visible in the code.
Pick by concept and support requirement
const needsBroadSupport = true;
if (needsBroadSupport) {
const instant = new Date("2026-01-01T09:30:00Z");
console.log(instant.toISOString());
}
Treating every date-time value as the same kind of thing
const value = new Date("2026-01-01");
// Is this a calendar date, a UTC instant, or a local display date?
Code patterns
Reusable examples for quick reference.
Dates and time zones become much easier when every example names the concept it represents: instant, local display, UTC output, calendar date, formatted text or zoned time.
Date for current browser support
Use Date when you need broad support without a polyfill.
const now = new Date(); console.log(now.toISOString());
Temporal for calendar dates
Use PlainDate when the value is only a date.
if ("Temporal" in globalThis) {
const date = Temporal.PlainDate.from("2026-01-01");
console.log(date.toString());
}
Date copy before set
Date setters mutate, so copy first.
const original = new Date("2026-01-01T09:30:00Z");
const changed = new Date(original.getTime());
changed.setUTCDate(changed.getUTCDate() + 7);
Temporal returns new values
Temporal methods usually return a new object.
if ("Temporal" in globalThis) {
const original = Temporal.PlainDate.from("2026-01-01");
const changed = original.add({ days: 7 });
console.log(original.toString());
console.log(changed.toString());
}
Rules that matter
Separate storage, logic and display.
Date-time bugs usually start when storage format, calculation logic and user-facing display are treated as the same thing. Keep those responsibilities separate and the code becomes much easier to trust.
Use Date when broad support is required
Date is still the universal baseline.
Use Temporal when support is available or polyfilled
It models date-time concepts more clearly.
Separate concepts before choosing tools
Instant, calendar date, wall-clock time and zoned time are different.
Avoid Date mutation leaks
Copy Date objects before using setters.
Feature-detect Temporal
Use "Temporal" in globalThis before browser use.
Keep display in Intl
Even with Temporal, formatting for people still belongs in Intl-style display logic.
Production thinking
Time is a data-modeling problem before it is a formatting problem.
Why does this matter?
The biggest improvement is not only syntax. It is thinking clearly about what kind of time value the code is handling.
Accessibility
Clear date-time modeling leads to clearer user-facing labels and less ambiguous scheduling or status text.
Production note
Production migration should be deliberate: keep Date where support matters, introduce Temporal with tests and fallback strategy.
SEO note
Stable date modeling helps prevent wrong published, modified or event dates in visible and structured content.
Live code lab
Change the HTML, CSS or JavaScript and run the result.
The preview runs inside an isolated iframe. The JavaScript is placed inside the HTML editor for now, so every example stays together and remains easy to understand.
Mini assignment
Try this now.
- Add one Date mutation example and copy before setting.
- Add a PlainDate add example inside the Temporal branch.
- Explain the output if Temporal is unavailable.
Practice assignment
Do this before moving to the next topic.
- List three concepts: instant, calendar date and zoned date-time.
- Write one Date example for broad support.
- Write one Temporal feature detection branch.
Try it yourself
Compare Date support with Temporal feature detection
Self-check
Before you continue, prove that you understand Temporal vs Date.
Dates are full of traps. Explain the concept first, then run the code and check whether the output matches your mental model.
- Can you explain why Date is still important?
- Can you explain why Temporal has clearer types?
- Can you explain why feature detection is required?
- Can you explain why mutation is a Date risk?
- Can you explain how Intl fits with both Date and Temporal?
Senior audit upgrade
Extra production context for Temporal vs Date.
Compatibility note: Temporal
Last reviewed: 11 June 2026. Keep Date for broad legacy compatibility. Use Temporal when your supported runtimes and build process allow it.
Source references
Use these references when browser support, syntax details or proposal status matters.
Chapter checkpoint
Dates, Time & Intl checkpoint
Finish this chapter by turning the lessons into a small practical proof.
Build
Build a small example that combines three lessons from this chapter.
Deliverables
- working code
- short explanation
- self-check answers
Quality checks
- readable code
- clear failure path
- accessibility considered
Review question
Can you explain the important tradeoff without reading from the page?