Temporal.PlainYearMonth.prototype.toString()

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 toString() method of Temporal.PlainYearMonth instances returns a string representing this year-month in the RFC 9557 format.

Syntax

toString()
toString(options)

Parameters

options Optional

An object containing the following property:

calendarName Optional

Whether to show the calendar annotation ([u-ca=calendar_id]) in the return value. Possible values are:

"auto" (default): Include the calendar annotation if the calendar is not "iso8601". The reference day is included if the calendar is not "iso8601".
"always": Always include the calendar annotation. The reference day is always included too.
"never": Never include the calendar annotation. This makes the returned string not recoverable to the same Temporal.PlainYearMonth instance, although the year-month value still remains the same. The reference day is included if the calendar is not "iso8601".
"critical": Always include the calendar annotation, and add a critical flag: [!u-ca=calendar_id]. Useful when sending the string to certain systems, but not useful for Temporal itself. The reference day is always included too.

Return value

A string in the RFC 9557 format representing this year-month. The calendar annotation is included as specified. The reference day is included if a calendar annotation is included or if the calendar is not "iso8601".

Exceptions

RangeError: Thrown if any of the options is invalid.
TypeError: Thrown if options is not an object or undefined.

Examples

Using toString()

const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8 });
console.log(ym.toString()); // '2021-08'

const ym2 = Temporal.PlainYearMonth.from({
  year: 4658,
  monthCode: "M08",
  calendar: "chinese",
});
console.log(ym2.toString()); // '2021-09-07[u-ca=chinese]'

Using options

const isoYM = Temporal.PlainYearMonth.from({ year: 2021, month: 8 });
const ym = Temporal.PlainYearMonth.from({
  year: 4658,
  monthCode: "M08",
  calendar: "chinese",
});
console.log(isoYM.toString({ calendarName: "auto" })); // '2021-08'
console.log(ym.toString({ calendarName: "auto" })); // '2021-09-07[u-ca=chinese]'
console.log(isoYM.toString({ calendarName: "always" })); // '2021-08-01[u-ca=iso8601]'
console.log(ym.toString({ calendarName: "always" })); // '2021-09-07[u-ca=chinese]'
console.log(isoYM.toString({ calendarName: "never" })); // '2021-08'
console.log(ym.toString({ calendarName: "never" })); // '2021-09-07'
console.log(isoYM.toString({ calendarName: "critical" })); // '2021-08-01[!u-ca=iso8601]'
console.log(ym.toString({ calendarName: "critical" })); // '2021-09-07[!u-ca=chinese]'

Specifications

Specification
Temporal proposal # sec-temporal.plainyearmonth.prototype.tostring

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
`toString`	No	No	No	No	No	No	No	No	No	No	No	1.40	No