formatYearMonth

Unreleased

Not in @northguild/gmt 1.20.0 on npm yet. It is on main and ships in the next release.

Signature

formatYearMonth(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string

Return a localized string for a year-month (YYYY-MM) using Intl options.

• Formats as Temporal’s ECMA-402 PlainYearMonth format does: only year, month and era are kept, at noon UTC on the first of the month.
• Gregorian rule (GMT). Always formats through the Gregorian calendar, which names the same year and month as the ISO one. ICU formats calendar: "iso8601" without the locale’s year-month pattern (Node prints "1970 " with no month name), and PlainYearMonth#toLocaleString throws for a calendar mismatch. A -u-ca- subtag in locale is overridden. With a calendar option, the calendar Intl resolves must be gregory or iso8601, otherwise "". Intl ignores an unsupported value and uses the locale’s default, so { calendar: "foo" } gives "10/2026" in en-US and "" in th-TH (Buddhist).
• dateStyle. The year and month widths are the locale’s own dateStyle date pattern’s, as ECMA-402 (AdjustDateTimeStyleFormat) and native PlainYearMonth#toLocaleString take them: en-US short is 10/26, de-DE medium 10/2026 and zh-CN long 2026/10. Polyfill 0.5.1 maps each style to fixed widths instead, so its toLocaleString prints Okt. 2026 for de-DE medium.
• A day, weekday, time field or timeZoneName is dropped; only those fields with no year or month give "", except timeZoneName, which falls back to the defaults. An era is kept.
• A year at or before 0 prints the Gregorian era year (0000 is year 1, -000001 is year 2) with no era unless era is asked for, as formatDate does.
• Returns "" for invalid input, a timeStyle, invalid options, null options or an ill-formed locale.

Parameters

Parameter	Type	Description
value	string	ISO year-month string
locale	string | string[]	optional BCP 47 locale identifier (default: runtime default), or a preference list of tags (ECMA-402)

Options

options

optional Intl.DateTimeFormatOptions

Type: DateTimeFormatOptions.

Option	Type	Default	Description
…Intl.DateTimeFormatOptions	—	—	Every field of DateTimeFormatOptions, as ECMA-402 defines it.

Returns

localized year-month string or "" on invalid input

Related types

• DateTimeFormatOptions

Examples

import { formatYearMonth } from "@northguild/gmt/plain/format";

formatYearMonth("2026-10", "en-US") // "10/2026"

value

locale (optional)

output

 

Source

plain/format/formatYearMonth.ts