# formatYearMonth

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
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`](/gmt/reference/types/DateTimeFormatOptions).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `…Intl.DateTimeFormatOptions` | — | — | Every field of [`DateTimeFormatOptions`](/gmt/reference/types/DateTimeFormatOptions), as [ECMA-402](https://tc39.es/ecma402/#sec-createdatetimeformat) defines it. |

## Returns

localized year-month string or "" on invalid input

## Related types

- [`DateTimeFormatOptions`](/gmt/reference/types/DateTimeFormatOptions)

## Examples

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

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

## Source

[plain/format/formatYearMonth.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/plain/format/formatYearMonth.ts)