Temporal.PlainDate.prototype.month

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 month accessor property of Temporal.PlainDate instances returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is 1, and the last month is the monthsInYear. It is calendar-dependent.

Note that unlike Date.prototype.getMonth(), the index is 1-based. If the calendar has leap months, then the month with the same monthCode may have different month indexes for different years.

Note: Do not use this property to identify the actual month, including its name. Use monthCode for that purpose. Use month only for identifying months within the context of a year, or to figure out their order.

The set accessor of month 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 month

js
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

Looping through all months in a year

js
const year = Temporal.PlainDate.from("2021-07-14"); // An arbitrary date in the year
for (
  let month = year.with({ month: 1 });
  month.year === year.year;
  month = month.add({ months: 1 })
) {
  console.log(month.month);
}

Alternatively, this is also a safe way (unlike the day example):

js
for (let month = 1; month <= year.monthsInYear; month++) {
  const monthDate = year.with({ month });
}

Changing month

js
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.

js
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:

js
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

Specifications

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

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
month
Experimental

Legend

Tip: you can click/tap on a cell for more information.

No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.

See also