native-dates

API / Functions

yearMonth() function

Read an ISO year-month string, card expiry, numbers, or date into a YearMonth.

import { yearMonth, monthYear } from 'native-dates'core 12.1 kB min+br

Reading year-months

yearMonth()

yearMonth(input, options?): YearMonth
yearMonth(input, zone?): YearMonth
yearMonth(year, month): YearMonth

Creates a YearMonth from an ISO year-month string, year and 1-indexed month numbers, a fields object, or any date or timestamp with its day dropped. Missing inputs throw a type error instead of defaulting to the current month.

billing.js
import { datetime, yearMonth } from 'native-dates';

const fromIso = yearMonth('2026-11');
const fromNumbers = yearMonth(2026, 11);
const fromFields = yearMonth({ year: 2026, month: 11 });
const fromDate = yearMonth('2026-11-16');
const fromInstant = yearMonth(datetime('2026-11-01T02:00:00Z'), 'America/Los_Angeles');

fromNumbers.toString(); // '2026-11'
fromInstant.toString(); // '2026-10'

Parameters

inputYearMonthInput | number | stringrequired

ISO year-month string, fields object, date or timestamp, or calendar year.

optionsZone | ReadOptions | number | string

Time zone or options object when reading a timestamp or loose string, or 1-indexed month from 1 to 12.

2 options
zoneZone

Time zone used to determine the calendar month of an instant string, DateTime, or Date.

loosebooleandefault false

Read English month names like 'Nov 2026' and return null on unreadable input with @native-dates/plugins/loose.

Returns

YearMonth

A YearMonth with no day, or null when loose mode cannot read input.

When the loose plugin is loaded, loose mode parses English month names beside a four-digit year and returns null on unreadable strings:

import { yearMonth } from 'native-dates';
import '@native-dates/plugins/loose';

yearMonth('Nov 2026', { loose: true })?.toString(); // '2026-11'
yearMonth('2026 November', { loose: true })?.toString(); // '2026-11'
yearMonth('not-a-month', { loose: true }); // null

monthYear()

monthYear(input, options?): YearMonth
monthYear(month, year): YearMonth

Reads month-first strings and numbers in the order printed on payment cards, such as '11/26'. Two-digit years from 0 through 99 are added to YearMonth.century, which defaults to 2000.

ISO strings written as '2026-11' still read year-first under both functions, so serialized values always round-trip cleanly.

Parameters

inputYearMonthInput | number | stringrequired

Card-expiry string like '11/26', any YearMonthInput, or 1-indexed month from 1 to 12.

optionsZone | ReadOptions | number | string

Time zone or options object, or two-digit or four-digit year when input is the month.

Returns

YearMonth

A YearMonth, or null when loose mode cannot read input.

import { monthYear } from 'native-dates';

monthYear('11/26').toString(); // '2026-11'
monthYear('05/2028').toString(); // '2028-05'
monthYear(11, 26).toString(); // '2026-11'
monthYear('2026-11').toString(); // '2026-11'

Accepted inputs

Months run from 1 for January through 12 for December across numbers, strings, and fields objects.

Input Example How it reads
ISO year-month string '2026-11' Reads the 4-digit year and 2-digit month directly, matching HTML month inputs.
Card expiry string monthYear('11/26'), monthYear('11.2026') Reads month first across /, -, or . and expands 2-digit years with YearMonth.century.
Two numbers yearMonth(2026, 11), monthYear(11, 26) Takes whole numbers in year-then-month or month-then-year order.
Fields object { year: 2026, month: 11 } Reads 1-indexed calendar fields and rejects months outside 1 through 12.
Date or timestamp '2026-11-16', datetime(...), new Date() Extracts the calendar month in the given zone or configured default and drops the day.
Loose month name 'Nov 2026', '2026 November' Reads English short or full month names with a 4-digit year in loose mode.
Temporal value Temporal.PlainYearMonth, Temporal.PlainDate Wraps ISO 8601 Temporal values directly.

Reading the current month

Read the active calendar month in any time zone via today(), such as today('Asia/Tokyo').yearMonth.

Edit this pageUpdated Nov 12, 2026