← All posts

Why JavaScript Months Start at Zero

JavaScript counts January as month 0 because its Date is a port of Java's original date class. Here is where that came from and how to stop it biting you.

A minimalist grey wall calendar turned to January, with the month printed as jan.
Photo by Behnam Norouzi on Unsplash

JavaScript calls January month 0 because Netscape ported Java's original date class into it, and Java's version matches the one C and Unix had used since the 1970s. That can never be fixed, so the real fix is to stop passing bare month numbers around and let date strings, Intl and Temporal do that work for you.

Once you see the family tree, the weird parts of Date stop looking random. They are fossils, and every one of them has a source.

The bug everyone writes once

Here is the classic version. A date input hands you a string, you split it, and you build a Date.

<label for="start">Start date</label>
<input type="date" id="start" name="start">
const value = "2026-12-25"; // what <input type="date"> gives you

// Before: off by one month
const [y, m, d] = value.split("-").map(Number);
const wrong = new Date(y, m, d);
console.log(wrong.toDateString()); // "Mon Jan 25 2027"

// After
const right = new Date(y, m - 1, d);
console.log(right.toDateString()); // "Fri Dec 25 2026"

The string from the input uses 1 for January and 12 for December, like every human calendar. The Date constructor takes a monthIndex that runs 0 through 11. So 12 is not December to Date. It is the month after December, and Date quietly rolls the extra month into the next year. No error. No warning. Christmas just moves to January.

That silent carry is its own trap. MDN documents it as intended behavior, so new Date(1990, 12, 1) gives you January 1, 1991. Out-of-range values are treated as arithmetic, never as mistakes.

Where month zero came from

C and Unix

The C standard library stores a broken-down date in a structure called struct tm. Its month field, tm_mon, runs 0 through 11, with January as 0. Its year field, tm_year, holds the year minus 1900. Jeff Kaufman went looking for the oldest version of this he could find and traced "month (0-11)" back to the Research Unix V4 manual from 1973.

The usual explanation is practical. A zero-based month drops straight into an array of month names, so names[tm_mon] just works. Days of the month stayed 1-based because people use them as numbers rather than array positions. That last part is my reading of the design, not a documented rule.

Java copies C

Java's first release shipped java.util.Date with the same shape. Oracle's docs still say it plainly. A month is an integer between 0 and 11, and the old constructor takes "the year minus 1900." Java deprecated those methods in JDK 1.1, which tells you how well they aged.

JavaScript copies Java

Brendan Eich has written that Ken Smith, a Netscape engineer who came over from Borland, ported the JDK 1.0-era java.util.Date into the new language. Eich said they were both following management orders to look like Java, and that they did not manage to avoid the Y2K bugs in that Java class either.

You can still see those bugs. getYear() is in every browser today and returns the year minus 1900. For a date in 2026 it returns 126. MDN marks it deprecated and calls it a year 2000 problem. It is the same tm_year field from 1970s C, carried through Java and into your browser console.

Why it can never change

The web does not break old pages. Millions of scripts already subtract 1 when they build a Date and add 1 when they read one. If getMonth() started returning 12 for December, all of that code would break at once. MDN's Temporal page says it directly. Date is based on the poorly designed java.util.Date, and it sticks around because of backward compatibility.

So the fix had to be a new API, and that API is Temporal.

How I keep month zero out of my code

Convert at the edge, once

Most month bugs happen at a boundary. A form, an API, a query string or a database all speak 1-based months. Date speaks 0-based. My rule is to convert in exactly one place and never pass a raw month number past it. If you see + 1 or - 1 sprinkled through a codebase near a date, that is where the bugs live.

For display, skip the month-name array entirely and let Intl.DateTimeFormat do it. You get the correct name in the user's language for free.

const label = new Intl.DateTimeFormat("en-US", { month: "long" }).format(right);
console.log(label); // "December"

If your date logic also depends on time zones, that is a second trap with the same flavor. I wrote about it in the Friday the 13th virus post.

Use Temporal where it ships

Temporal treats months the way people do. Temporal.PlainDate represents a calendar date with no time and no time zone, and its month property is 1-based. It also parses the exact string a date input gives you.

if (typeof Temporal !== "undefined") {
  const day = Temporal.PlainDate.from("2026-12-25");
  console.log(day.month);                         // 12
  console.log(day.add({ months: 1 }).toString()); // "2027-01-25"

  // Month math clamps instead of spilling over
  const jan31 = Temporal.PlainDate.from("2026-01-31");
  console.log(jan31.add({ months: 1 }).toString()); // "2026-02-28"
}

Compare that last line with Date. Take January 31, 2026 and call setMonth(1) on it. You get March 3, because February 31 does not exist and Date carries the extra days forward. Temporal clamps to the last valid day by default, and you can pass { overflow: "reject" } to throw a RangeError instead.

const jan31 = new Date(2026, 0, 31);
jan31.setMonth(1);
console.log(jan31.toDateString()); // "Tue Mar 03 2026"

When Temporal is the wrong call today

Temporal is not Baseline yet. Chrome and Edge 144 and Firefox 139 ship it. Safari's stable release does not, and the web-features explorer lists Safari as the browser holding Baseline back. For a public site, that means either a polyfill or a Date fallback behind the feature check above. A polyfill adds weight to every page load, so for one date field the honest answer may be a careful m - 1 with a comment next to it.

Temporal also makes you pick the right type. PlainDate has no time zone on purpose. If you need an exact moment, such as when an order was placed, you want Temporal.Instant or Temporal.ZonedDateTime instead. That choice is a feature, but it is one more thing a beginner has to learn on day one.

And zero-based months are not wrong in themselves. They make sense as an array index. The trouble is mixing them with the 1-based months every other system uses.

Wrap-up

Month zero is a 1973 Unix convention that rode into Java and then into JavaScript under deadline pressure. It will be in Date forever. Treat Date's month index as an internal detail, convert once at the edge, format with Intl, and reach for Temporal.PlainDate where your browsers support it. The next time someone on your team asks why December is 11, you can tell them it is a fossil from the 1990s.

Sources