Is the JavaScript Temporal API Ready Yet?

Can you use the JavaScript Temporal API yet?

As of October 2026, the standard is finished and the browsers are not. Temporal sits in TC39's finished proposals list with an expected publication year of 2027, so the design is settled. MDN still marks it as limited availability and says it is not Baseline because it does not work in some of the most widely-used browsers.

That combination is unusual and worth understanding. Normally a feature is either still being argued about or safe to ship. Temporal is neither. The committee has stopped changing it and the rollout is incomplete.

So the practical question is not whether Temporal is good. It is what you do with dates for the next year or two while the thing that fixes them finishes arriving.

What is Temporal?

A replacement for Date, built as a namespace of purpose-specific types. MDN describes it as a JavaScript namespace object designed as a full replacement for the Date object, covering built-in time zone and calendar representation, wall-clock time conversions, arithmetic, and formatting.

The design idea is that a moment in time and a date on a calendar are different things and should be different types. Date tried to be both. Temporal splits them, which means the type you choose records what you actually meant.

That split is the whole reason it is worth caring about. Most date bugs we see in production are not arithmetic errors. They are a timestamp being treated as a calendar date, or a calendar date being given a time zone it never had.

What is actually wrong with the Date object?

Five specific things, and MDN lists them. Date inherited its design flaws from Java's java.util.Date. The first is that Date objects act simultaneously as timestamps in milliseconds since the epoch and as combinations of components like year, month, and day, which MDN says leads to unexpected pitfalls.

The second is time zones. MDN notes that only UTC and the local device time zone are accessible, with no way to specify an arbitrary time zone or wall-clock time, meaning calendar and clock time independent of any zone. If you have ever stored a meeting time and watched it move for someone in another country, that is this.

The rest are calendars, mutation, and parsing. MDN points out that Date supports only the Gregorian calendar and lacks Hebrew, Chinese, Japanese, and other systems; that all its setters mutate and cause unwanted side effects; and that its date-time string format is impossible to parse consistently.

Where does Temporal stand as a standard?

Done. Temporal appears in TC39's finished proposals list, which is the Stage 4 list, with an expected publication year of 2027. Its champion list is long and spans years of meeting notes, running from 2017 to 2026.

Stage 4 means the specification text is written, the tests exist, and implementations are expected rather than speculative. From a standards point of view there is nothing left to wait for. The API you learn today is the API that ships.

That is genuinely useful to know, because it changes how you should spend learning time. Studying a Stage 2 proposal is often wasted effort. Studying a finished one is not, even if you cannot ship it for another year.

Why is it not Baseline yet?

Because Baseline is a support measurement, not a specification one. MDN's Baseline definitions are specific: widely available means a feature has a consistent history of support in each of the Baseline browsers for at least 2.5 years, and newly available means it works in at least the latest stable version of each of them.

That core browser set is Safari on iOS and macOS, Chrome on Android and desktop, Edge on desktop, and Firefox on Android and desktop. Temporal does not currently clear even the newly available bar, which is what MDN's limited availability label means.

The gap between Stage 4 and Baseline widely available is structurally at least 2.5 years once the last browser ships, by definition. Anyone telling you Temporal is ready because the standard is finished has confused two different kinds of ready. Our notes on reading Baseline cover why that distinction keeps mattering.

What do the main Temporal types do?

Each one records a different kind of time, and picking the right one is most of the benefit. MDN lists Temporal.Instant as a unique point in time with nanosecond precision, and Temporal.ZonedDateTime as a date-time with a time zone attached.

Then there are the plain types, which deliberately carry no zone. MDN lists Temporal.PlainDateTime for a date and time without a time zone, Temporal.PlainDate for a calendar date only, Temporal.PlainTime for a time without a date or zone, plus Temporal.PlainYearMonth and Temporal.PlainMonthDay for partial dates.

Temporal.Duration rounds it out as the time difference between two points. The reason this list matters is that a birthday is a PlainMonthDay, a publication date is usually a PlainDate, a server log entry is an Instant, and a scheduled call is a ZonedDateTime. Date made all four look identical.

Should you use a polyfill?

Only if dates are genuinely the hard part of your product. A polyfill for a large API like this is not small, and you would be shipping a full date library to every visitor to get an API you could have waited for. That is a reasonable trade for a scheduling product and a poor one for a marketing site.

The honest comparison is against the date library you are probably already shipping. If you have a mature library doing the job, swapping it for a Temporal polyfill buys you future compatibility and costs you churn today. If you are about to add a date library, learning the standard shape first is sensible.

We would weigh it like any other dependency: what does it cost on first load, who maintains it, and what happens when native support lands. Our notes on reducing bundle size cover the measurement side of that question.

Does any of this change anything for a marketing site?

Rarely, and that is worth saying plainly. Most marketing sites format a publication date and nothing else. The built-in internationalisation formatting already handles that well, and no date arithmetic is involved, so Temporal solves a problem the site does not have.

Where it does show up is anything scheduling-shaped: webinar times across regions, event listings, booking widgets, countdowns to a launch. Those are exactly the cases where Date's missing time zone support bites, and they are common enough on B2B sites to be worth getting right.

The other case is content pipelines. If your CMS stores a publish timestamp and your build renders it, the gap between a calendar date and an instant becomes a real decision. Pick one, store it consistently, and do not let the two meanings mix.

What should you do now instead of waiting?

Fix the modelling, which is free. Decide for each date in your system whether it is an instant, a calendar date, or a wall-clock time, and write that down. Temporal will make that distinction enforceable later; nothing stops you from being disciplined about it today.

Store instants in UTC and format at the edges. Most date bugs come from converting too early or too often, and that habit is independent of which API you use. If your database holds one unambiguous value and your templates do the formatting, swapping libraries later is a small job.

Name your fields honestly too. A column called date that actually holds a timestamp is how the confusion spreads from code into schemas, and schemas outlive code. Our notes on time zones and dates in product UX cover the user-facing half of this.

How are we handling dates in the meantime?

Conservatively, and with one rule. Everything is stored in UTC, and any display conversion happens as late as possible. That single rule removes most of the ambiguity Date creates without needing a new API at all.

We also avoid date arithmetic in templates. Working out whether something is in the past, or how long ago it was published, belongs in one place where it can be tested rather than scattered through markup. That is a habit, not a library.

What we are not doing is adopting Temporal on client work yet. MDN's label is the right call for us: limited availability means some real visitors would get a broken page, and a cleaner date API is not worth that. We will revisit when it clears newly available across the Baseline set.

When will Temporal actually be safe to ship?

Watch Baseline rather than the calendar. The specification is already finished with a 2027 publication year, so the remaining variable is browser rollout. The moment Temporal reads as newly available on MDN, it becomes a reasonable choice for products that can require current browsers.

Widely available is a longer wait by construction, since that label requires 2.5 years of consistent support after the last browser lands. For client work with broad audiences, that is the line we will use, and we would rather say so than pretend the standard being done settles it.

If you are modelling dates for a product and want a second opinion before you commit to a schema, we are happy to look at it with you. We are at phoenix.studio.