Temporal.PlainMonthDay.prototype.toLocaleString()

Syntax

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Parameters

The locales and options parameters customize the behavior of the function and let applications specify the language whose formatting conventions should be used.

In implementations that support the Intl.DateTimeFormat API, these parameters correspond exactly to the Intl.DateTimeFormat() constructor's parameters. Implementations without Intl.DateTimeFormat support return the exact same string as toString(), ignoring both parameters.

locales Optional

A string with a BCP 47 language tag, or an array of such strings. Corresponds to the locales parameter of the Intl.DateTimeFormat() constructor.

options Optional

An object adjusting the output format. Corresponds to the options parameter of the Intl.DateTimeFormat() constructor. The calendar option must be provided with the same value as this month-day's calendar. Regarding the date-time component options and the style shortcuts (dateStyle and timeStyle), the options should follow one of these forms:

• Provide none of them: month and day will default to "numeric".
• Provide dateStyle only: it expands to month and day formats.
• Provide some date-time component options, where at least one of them is month or day. Only the specified date components will be included in the output.

See the Intl.DateTimeFormat() constructor for details on these parameters and how to use them.

Return value

A string representing the given month-day according to language-specific conventions.

In implementations with Intl.DateTimeFormat, this is equivalent to new Intl.DateTimeFormat(locales, options).format(monthDay), where options has been normalized as described above.

Exceptions

RangeError

Thrown if any of the options is invalid.

TypeError

Thrown if any of the options is not of the expected type.

Examples

Using toLocaleString()

Basic use of this method without specifying a locale returns a formatted string in the default locale and with default options.

// Note that just specifying "08-01" defaults to the ISO 8601 calendar,
// which throws an error if the locale's default calendar is not ISO 8601.
const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]");

console.log(md.toLocaleString()); // 8/1 (assuming en-US locale and Gregorian calendar)

If the month-day's calendar doesn't match the locale's default calendar, even when its calendar is iso8601, an explicit calendar option must be provided with the same value.

const md = Temporal.PlainMonthDay.from("08-01");
md.toLocaleString("en-US", { calendar: "iso8601" }); // 08-01

Using toLocaleString() with options

You can customize which parts of the month-day are included in the output by providing the options parameter.

const md = Temporal.PlainMonthDay.from("2021-08-01[u-ca=gregory]");
md.toLocaleString("en-US", { dateStyle: "full" }); // August 1
md.toLocaleString("en-US", { month: "long" }); // August
md.toLocaleString("en-US", { day: "numeric" }); // 1

Specifications

Browser compatibility

See also

• Temporal.PlainMonthDay
• Intl.DateTimeFormat
• Temporal.PlainMonthDay.prototype.toJSON()
• Temporal.PlainMonthDay.prototype.toString()