# formatMonthDay

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

## Signature

```ts
formatMonthDay(value: string, locale?: string | string[], options?: DateTimeFormatOptions): string
```

Return a localized string for a month-day (`--MM-DD` or `MM-DD`) using Intl options.

- Formats as Temporal's ECMA-402 PlainMonthDay format does: only `month` and `day` are kept, at noon UTC on the ISO date in the 1972 reference year (so `--02-29` formats). The year is never printed.
- **Gregorian rule (GMT).** Always formats through the Gregorian calendar, which names the same month and day as the ISO one. ICU formats `calendar: "iso8601"` without the locale's month-day pattern (Node prints `" 25"`, browsers `Dezember 25` for de-DE), and `PlainMonthDay#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 `"12/25"` in en-US and `""` in th-TH (Buddhist).
- **`dateStyle`.** The month and day widths are the locale's own `dateStyle` date pattern's, as ECMA-402 (AdjustDateTimeStyleFormat) and native `PlainMonthDay#toLocaleString` take them: de-DE `medium` is `25.12.`, en-US `medium` `Dec 25` and zh-CN `long` `12/25`. Polyfill 0.5.1 maps each style to fixed widths instead, so its `toLocaleString` prints `25. Dez.` for de-DE `medium`.
- A `year`, `weekday`, `era`, time field or `timeZoneName` is dropped; only those fields with no `month` or `day` give `""`, except `era` and `timeZoneName`, which fall back to the defaults.
- Returns `""` for invalid input, a `timeStyle`, invalid options, `null` options or an ill-formed locale.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `value` | `string` | ISO month-day 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 month-day string or "" on invalid input

## Related types

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

## Examples

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

formatMonthDay("--12-25", "en-US") // "12/25"
```

## Source

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