JavaScript Date Object is Replaced: How to use it!

The JavaScript Date object has powered everything from clocks to calendars since 1995, and it still ships in every browser. But it has also been a long-running source of bugs: mutable objects, weird parsing, and painful time-zone math. In 2026, that finally changes. The modern Temporal API reached the final spec stage and is landing in browsers, giving JavaScript a proper date-and-time toolkit at last.

This guide covers both sides of the story: how to use the Date object correctly today, and how to move to Temporal as support rolls out.

How do you use the JavaScript Date object?

You create a date with the new Date() constructor. It accepts four kinds of input, and knowing them removes most of the confusion beginners hit.

Creating a Date with new Date()

// 1. Current date and time (no arguments)
const now = new Date();

// 2. From a date string (ISO 8601 is the only safe format)
const iso = new Date('2026-05-03T14:30:00Z');

// 3. From individual components: year, monthIndex, day, hours, minutes, seconds, ms
// NOTE: the month is 0-indexed — 4 means May, not April.
const may = new Date(2026, 4, 3, 14, 30, 0);

// 4. From a timestamp (milliseconds since the Unix epoch, 1 Jan 1970 UTC)
const fromEpoch = new Date(1746282600000);

The single most common mistake is the 0-indexed month: January is 0 and December is 11. The day-of-month and year are 1-based, which makes it easy to be off by one.

Reading date and time values

Once you have a Date, getter methods return each component in local time (there are matching getUTC* versions for UTC).

const d = new Date('2026-05-03T14:30:15');

d.getFullYear();   // 2026
d.getMonth();      // 4  (May — remember, 0-indexed)
d.getDate();       // 3  (day of the month, 1-31)
d.getDay();        // 0  (day of the week, 0 = Sunday)
d.getHours();      // 14
d.getMinutes();    // 30
d.getSeconds();    // 15
d.getTime();       // milliseconds since the epoch

Setting and changing date values

Date objects are mutable — setter methods change the object in place rather than returning a new one. This is a frequent source of hard-to-trace bugs.

const d = new Date('2026-05-03');

d.setFullYear(2027);
d.setMonth(11);      // December
d.setDate(25);       // 25 Dec 2027

// Add 7 days — setDate handles month/year rollover automatically
d.setDate(d.getDate() + 7);

Formatting a Date object

For machine-readable output use toISOString(). For user-facing strings, prefer Intl.DateTimeFormat or toLocaleDateString() over the legacy toString() methods.

const d = new Date('2026-05-03T14:30:00Z');

d.toISOString();            // "2026-05-03T14:30:00.000Z"
d.toLocaleDateString('en-US', { dateStyle: 'full' });
// "Sunday, May 3, 2026"

new Intl.DateTimeFormat('fr-FR', { dateStyle: 'long' }).format(d);
// "3 mai 2026"

Comparing and calculating with dates

const a = new Date('2026-05-03');
const b = new Date('2026-05-10');

a < b;                       // true — comparison operators work
const msApart = b - a;       // 604800000 (ms) — subtraction gives a duration
const daysApart = msApart / (1000 * 60 * 60 * 24); // 7

Equality is the catch: a === b compares object references, not values, so it is almost always false. Compare with a.getTime() === b.getTime() instead.

Why is the JavaScript Date object being replaced?

Date was modeled on Java's early date classes and copied their flaws. Java moved on; JavaScript could not, because the web can't break existing sites. The pain points are well known:

• Limited time-zone support — only UTC and the machine's local zone; no arbitrary IANA zones.
• Mutable objects — setters change state in place, causing action-at-a-distance bugs.
• Inconsistent parsing — non-ISO strings behave differently across browsers.
• Fragile daylight-saving math — transitions are easy to get wrong.
• No durations or intervals — you reach for a library for anything beyond a raw timestamp.

This is why teams have long relied on Moment.js, date-fns, and Luxon to fill the gaps. Temporal folds those capabilities into the language itself.

What is the Temporal API?

The Temporal API is a new global namespace that replaces Date with precise, immutable, timezone-aware types. It reached TC39 Stage 4 on 11 March 2026 and is part of the ES2026 specification, so it is now a finished, standardized feature rather than a proposal.

Highlights:

• Immutable objects — every operation returns a new value.
• Native time-zone and calendar support — full IANA zones and non-Gregorian calendars.
• Reliable ISO 8601 parsing — no browser-to-browser surprises.
• Clear separation of concepts — dates, times, instants, and durations are distinct types.

"Temporal is designed as a full replacement for the Date object, making date and time management reliable and predictable." — MDN Web Docs

How does Temporal compare to Date?

How do you get started with Temporal?

Key Temporal classes

• Temporal.PlainDate — a calendar date with no time or zone.
• Temporal.PlainTime — a wall-clock time with no date.
• Temporal.PlainDateTime — combined date and time, no zone.
• Temporal.ZonedDateTime — date and time anchored to a time zone.
• Temporal.Instant — an exact moment on the global timeline.
• Temporal.Duration — a length of time.

Creating Temporal objects

const date = Temporal.PlainDate.from('2026-05-03');
const time = Temporal.PlainTime.from('14:30:00');
const dateTime = Temporal.PlainDateTime.from('2026-05-03T14:30:00');
const zoned = Temporal.ZonedDateTime.from({
  year: 2026, month: 5, day: 3, hour: 14, minute: 30,
  timeZone: 'Asia/Kolkata'
});
const now = Temporal.Now.instant();

Note that Temporal months are 1-based, so month: 5 is May — the opposite of Date.

How do you work with time zones and calendars in Temporal?

// Time zones
const nyTime = Temporal.ZonedDateTime.from({
  year: 2026, month: 5, day: 3, hour: 10, minute: 0,
  timeZone: 'America/New_York'
});

// Non-Gregorian calendars
const japaneseDate = Temporal.PlainDate.from({
  year: 2026, month: 5, day: 3, calendar: 'japanese'
});

How do you manipulate dates and times with Temporal?

const date = Temporal.PlainDate.from('2026-05-03');
const nextWeek = date.add({ days: 7 });   // returns a NEW date

const d1 = Temporal.PlainDate.from('2026-05-03');
const d2 = Temporal.PlainDate.from('2026-05-10');
d1.equals(d2);            // false — real value equality
d1.until(d2).days;        // 7

const duration = Temporal.Duration.from({ days: 3, hours: 5 });

Because every method returns a new object, the original is never mutated — the class of bug that plagues Date simply cannot happen.

How do you format and parse with Temporal?

const date = Temporal.PlainDate.from('2026-05-03');
date.toLocaleString('en-US', { dateStyle: 'full' });
// "Sunday, May 3, 2026"

const formatter = new Intl.DateTimeFormat('fr-FR', { dateStyle: 'full' });
formatter.format(date);
// "dimanche 3 mai 2026"

How do you migrate from Date to Temporal?

You do not need a big-bang rewrite. Convert at the boundaries — turn legacy Date values into Temporal at the edge of your code, and back again when an API still expects a Date.

// Date -> Temporal
const legacy = new Date();
const instant = Temporal.Instant.fromEpochMilliseconds(legacy.getTime());
const zoned = instant.toZonedDateTimeISO('Asia/Kolkata');

// Temporal -> Date
const nowInstant = Temporal.Now.instant();
const jsDate = new Date(nowInstant.epochMilliseconds);

Which browsers support Temporal in 2026?

Support is now real, not experimental:

• Firefox 139 (May 2025) was the first browser to ship Temporal on by default.
• Chrome 144 (January 2026) shipped it, covering most desktop users.
• Edge has it in beta; Safari exposes most of the API in Technology Preview.

For everything else, use the @js-temporal/polyfill (or the lighter temporal-polyfill). Both track the Stage 4 spec, so you can write Temporal code today and drop the polyfill later without changing your app.

Best practices and common pitfalls

• With Date, remember months are 0-indexed and objects are mutable — copy before mutating.
• Only parse ISO 8601 strings with Date; anything else is browser-dependent.
• With Temporal, reach for ZonedDateTime whenever a real place and time matter, and PlainDate/PlainTime when they do not.
• Use Temporal.Instant as the bridge when converting from a legacy Date.

FAQ

Is the JavaScript Date object deprecated?

Not yet. Date still works in every browser and is not formally deprecated. Once Temporal has full cross-browser support, Date will be treated as a legacy feature, but existing code will keep running for the foreseeable future.

How do I create a date in JavaScript?

Call new Date(). With no arguments you get the current moment; you can also pass an ISO 8601 string, individual components (year, monthIndex, day, ...), or a millisecond timestamp. Remember the month argument is 0-indexed.

Why is the month off by one in JavaScript dates?

The Date constructor and getMonth() use a 0-based month index: January is 0 and December is 11. Temporal fixes this by using intuitive 1-based months.

Do I still need Moment.js or date-fns?

For new projects, increasingly no. Temporal covers time zones, durations, and calendars natively. Moment.js is in maintenance mode; date-fns and Luxon remain useful today, and several libraries are moving to build on Temporal under the hood.

Can I use Temporal in production now?

Yes, with a polyfill. Temporal is a finished ES2026 feature and ships natively in Firefox and Chrome. Add @js-temporal/polyfill to cover browsers that haven't shipped it yet, then remove it once native support is universal.

Conclusion

The Date object isn't going away tomorrow — knowing how to create, read, and format it correctly still matters. But Temporal is now a shipped standard, and it removes the mutability, time-zone, and parsing traps that made Date so error-prone. Learn Date's quirks, adopt Temporal at your boundaries, and your date handling gets predictable.

Building a product that leans on solid date-and-time logic? Codersera can help you extend your team with vetted JavaScript developers who ship reliable code.