Temporal.PlainDate.prototype.monthCode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The monthCode accessor property of Temporal.PlainDate instances returns a calendar-specific string representing the month of this date. It is calendar-dependent.

Usually it is M plus a two-digit month number. For leap months, it is the previous month's code followed by L (even if it's conceptually a derivative of the following month; for example, in the Hebrew calendar, Adar I has code M05L but Adar II has code M06). If the leap month is the first month of the year, the code is M00L.

Note: Don't assume that monthCode is a user-friendly string; use toLocaleString() to format your date instead. Generally, don't cache the name of months in an array or object. Even though monthCode usually maps to the month's name within one calendar, we recommend always computing the month's name using, for example, date.toLocaleString("en-US", { calendar: date.calendarId, month: "long" }).

The set accessor of monthCode is undefined. You cannot change this property directly. Use the with() method to create a new Temporal.PlainDate object with the desired new value.

Examples

Using monthCode

const date = Temporal.PlainDate.from("2021-07-01"); // ISO 8601 calendar
console.log(date.monthCode); // "M07"
console.log(date.month); // 7

const date2 = Temporal.PlainDate.from("2021-05-01[u-ca=chinese]");
console.log(date2.monthCode); // "M03"
console.log(date2.month); // 3; it is March 20 in the Chinese calendar

const date3 = Temporal.PlainDate.from("2023-05-01[u-ca=chinese]");
console.log(date3.monthCode); // "M03"
console.log(date3.month); // 4, although it is also March (M03)!

const date4 = Temporal.PlainDate.from("2023-04-01[u-ca=chinese]");
console.log(date4.monthCode); // "M02L"
console.log(date4.month); // 3, this month is a leap month, i.e. a duplicate February

Changing monthCode

const date = Temporal.PlainDate.from("2021-07-01");
const newDate = date.with({ month: 2 });
console.log(newDate.toString()); // 2021-02-01

You can also use add() or subtract() to move a certain number of months from the current date.

const date = Temporal.PlainDate.from("2021-07-01");
const newDate = date.add({ months: 3 });
console.log(newDate.toString()); // 2021-10-01

By default, with() constrains the day to the range of valid values. Both of the following will set the month to the last month of the year:

const date = Temporal.PlainDate.from("2021-07-01");
const lastMonth = date.with({ month: date.monthsInYear }); // 2021-12-01
const lastMonth2 = date.with({ month: Number.MAX_VALUE }); // 2021-12-01

Formatting month names

Don't do this:

const names = [
  "January", "February", "March", "April", "May", "June",
  "July", "August", "September", "October", "November", "December"
];

const date = Temporal.PlainDate.from("2021-07-01");
console.log(names[date.month - 1]); // July

Also don't do this:

const names = {
  "M01": "January", "M02": "February", "M03": "March", "M04": "April",
  "M05": "May", "M06": "June", "M07": "July", "M08": "August",
  "M09": "September", "M10": "October", "M11": "November", "M12": "December"
};

const date = Temporal.PlainDate.from("2021-07-01");
console.log(names[date.monthCode]); // July

Instead, always do this, which is more user-friendly and less error-prone, and easily generalizes to other calendars:

const date = Temporal.PlainDate.from("2021-07-01");
console.log(
  date.toLocaleString("en-US", { calendar: date.calendarId, month: "long" }),
); // July

Specifications

Specification
Temporal proposal # sec-get-temporal.plaindate.prototype.monthcode

Browser compatibility

	Desktop					Mobile						Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	Deno	Node.js
`monthCode`	No	No	No	No	No	No	No	No	No	No	No	1.40	No