API / Classes

`YearMonth` class

A calendar year and month with no day, for billing periods, card expiries, and month pickers.

import { YearMonth } from 'native-dates'core 12.1 kB min+br

Creating a YearMonth

Create an instance from an ISO string, year and month numbers, or an existing date with yearMonth(), or read card-expiry strings month-first with monthYear(). Instances are immutable, so every method that changes a value returns a new one.

create.js

import { monthYear, yearMonth } from 'native-dates';

const billing = yearMonth('2026-11');
const quarterEnd = yearMonth(2026, 12);
const expiry = monthYear('11/26');

Read the year and month off any calendar date or moment through its yearMonth property, or convert inside a chain with as('yearMonth'):

import { date, datetime, today } from 'native-dates';

date('2026-11-16').yearMonth.toString(); // '2026-11'
datetime('2026-11-01T02:00:00Z', 'America/Los_Angeles').as('yearMonth').toString(); // '2026-10'
const currentMonth = today().yearMonth;

Properties

Properties read the ISO year, month, and surrounding calendar bounds.

Property	Type	Description
`text`	`string`	Locale-formatted month and year, such as `'Nov 2026'`.
`year`, `month`	`number`	Calendar year and 1-indexed month from 1 through 12.
`quarter`	`number`	Calendar quarter from 1 through 4.
`daysInMonth`, `daysInYear`	`number`	Days in this month from 28 to 31, and days in this year as 365 or 366.
`start`, `end`	`CalendarDate`	First and last calendar day of this month.
`YearMonth.century`	`number`	Base century added to two-digit years in `monthYear()`, defaulting to `2000`.
`YearMonth.presets`	`object`	Named format presets read by `format()`, open to custom entries.

Arithmetic and fields

Step forward or backward by months, quarters, or years, replace fields, or pick a specific day of the month.

Month and year units only

Units smaller than a month throw a RangeError because a year-month carries no day. Call on() to pick a day first when you need week or day math.

`plus()`

ym.plus(amount, unit?): YearMonth
ym.add(amount, unit?): YearMonth

Moves forward by years, quarters, or months and returns a new YearMonth. Also aliased as add().

Parameters

amountDurationInputrequired

Count paired with unit, Duration instance, duration string, or fields object.

unitUnit

Month, quarter, or year unit name when amount is a number.

Returns

YearMonth

A new YearMonth shifted forward on the calendar.

const billing = yearMonth('2026-11');

billing.plus(3, 'months').toString(); // '2027-02'
billing.plus('1 year').toString(); // '2027-11'

`minus()`

ym.minus(amount, unit?): YearMonth
ym.subtract(amount, unit?): YearMonth
ym.remove(amount, unit?): YearMonth

Moves backward by years, quarters, or months and returns a new instance. Accepts the same inputs as plus(), with subtract() and remove() as aliases.

Parameters

amountDurationInputrequired

Count paired with unit, Duration instance, duration string, or fields object.

unitUnit

Month, quarter, or year unit name when amount is a number.

Returns

YearMonth

A new YearMonth shifted backward on the calendar.

yearMonth('2026-11').minus(1, 'year').toString(); // '2025-11'

`set()`

ym.set(fields): YearMonth
ym.set(unit, value): YearMonth

Returns a new YearMonth with the year, month, or both replaced. Out-of-range months and units smaller than a month throw a RangeError.

Parameters

fieldsPartial<YearMonthFields> | Unitrequired

Object with year or month fields, or a single unit name.

valuenumber

Whole-number value when passing a unit name.

Returns

YearMonth

A new YearMonth with updated calendar fields.

const billing = yearMonth('2026-11');

billing.set('month', 2).toString(); // '2026-02'
billing.set({ year: 2028, month: 2 }).daysInMonth; // 29

`on()`

ym.on(day): CalendarDate

Places a whole day number from 1 through 31 in this month and returns a CalendarDate. Day 31 clamps to the final day of shorter months such as February or April, while numbers outside 1 to 31 throw a RangeError.

Parameters

daynumber | stringrequired

Whole day of the month from 1 through 31.

Returns

CalendarDate

The CalendarDate for that day of the month.

yearMonth('2026-11').on(15).toString(); // '2026-11-15'
yearMonth('2026-02').on(31).toString(); // '2026-02-28'
yearMonth('2028-02').on(31).toString(); // '2028-02-29'

Comparison and containment

Compare year-months chronologically or check whether a calendar day falls inside the month. Relational operators like < throw an error, while arrays sort cleanly with compare() and boundary helpers.

`compare()`

ym.compare(other): -1 | 0 | 1

Orders this year-month against another, returning negative, zero, or positive numbers for sorting. Passing a full date or timestamp compares against the month it falls in.

Parameters

otherYearMonthInputrequired

Another YearMonth or any input accepted by yearMonth().

Returns

-1 | 0 | 1

Returns -1 when earlier, 0 when equal, and 1 when later.

yearMonth('2026-05').compare('2026-11'); // -1
yearMonth('2026-11').compare('2026-11-16'); // 0

`equals()`

ym.equals(other): boolean

Returns true when both values represent the same year and month.

yearMonth('2026-11').equals(yearMonth(2026, 11)); // true

`isBefore()`

ym.isBefore(other): boolean

Returns true when this year-month comes earlier than the other.

yearMonth('2026-10').isBefore('2026-11'); // true

`isAfter()`

ym.isAfter(other): boolean

Returns true when this year-month comes later than the other.

yearMonth('2026-12').isAfter('2026-11'); // true

`contains()`

ym.contains(day): boolean

Returns true when the given calendar date or timestamp falls inside this year and month.

Parameters

dayCalendarDateInputrequired

Date string, CalendarDate, DateTime, fields object, or Date.

Returns

boolean

true when day falls within this month.

const nov = yearMonth('2026-11');

nov.contains('2026-11-16'); // true
nov.contains('2026-12-01'); // false

`isPast()`

ym.isPast(zone?): boolean

Returns true once this entire month is earlier than today’s month in the given or configured time zone.

yearMonth('2020-01').isPast('UTC'); // true

`isFuture()`

ym.isFuture(zone?): boolean

Returns true while this month is still ahead of today’s month in the given or configured time zone.

yearMonth('2099-01').isFuture('UTC'); // true

`isLeapYear()`

ym.isLeapYear(): boolean

Returns true when this month’s calendar year has 366 days.

yearMonth('2028-02').isLeapYear(); // true
yearMonth('2026-02').isLeapYear(); // false

Measuring spans

`until()`

ym.until(other): Duration
ym.until(other, unit): number

Measures the span from this month to another, returning a negative duration when the target is earlier. The returned Duration remembers the start of this month so months and years can be totaled in any unit.

Parameters

otherYearMonthInputrequired

Target year-month to measure toward.

unitUnit

Unit name to return the total span in as a floating-point number.

Returns

Duration | number

A Duration of years and months, or a number when unit is given.

const start = yearMonth('2026-03');

start.until('2027-06').toString(); // 'P1Y3M'
start.until('2027-06', 'months'); // 15

`since()`

ym.since(other): Duration
ym.since(other, unit): number

Measures the span elapsed since an earlier year-month. Pass a unit name to get the total as a number.

yearMonth('2026-11').since('2026-05', 'months'); // 6

Formatting and conversion

`format()`

ym.format(spec?, locale?): string

Formats the year and month using named presets, Intl options objects, or built-in token patterns such as 'MM/YY'. Shared options objects drop day, clock, and zone keys automatically.

Standard and localized presets print only the year and month, and custom styles can be added on YearMonth.presets. See Formatting for the full preset and token tables.

Parameters

specFormatSpecdefault 'medium'

Preset name such as 'medium' or 'long', Intl options object, or token pattern.

localeLocale

BCP 47 locale tag overriding the configured default for this call.

Returns

string

Formatted month-and-year string.

const nov = yearMonth('2026-11');

nov.format('short', 'en-US'); // '11/26'
nov.format('medium', 'en-US'); // 'Nov 2026'
nov.format('long', 'en-US'); // 'November 2026'
nov.format('L', 'en-US'); // '11/2026'
nov.format('MM/YY'); // '11/26'

`as()`

ym.as('yearMonth'): YearMonth

Returns this instance when 'yearMonth' is requested in generic conversion chains, throwing a RangeError for other kinds.

`toString()`

ym.toString(): string
ym.toJSON(): string

Returns the ISO 8601 year-month string, matching month form inputs in HTML. toJSON() returns the same string for JSON serialization.

Returns

string

ISO 8601 year-month string such as '2026-11'.

yearMonth(2026, 11).toString(); // '2026-11'
JSON.stringify({ billing: yearMonth(2026, 11) }); // '{"billing":"2026-11"}'

`toTemporal()`

ym.toTemporal(): Temporal.PlainYearMonth

Returns the underlying Temporal.PlainYearMonth instance.

`valueOf()`

ym.valueOf(): never

Throws a RangeError so numeric operators never coerce a year-month to a number. Narrow unknown values with isYearMonth() or kindOf().

Edit this pageUpdated Nov 12, 2026

YearMonth class

Creating a YearMonth

Properties

Arithmetic and fields

plus()

minus()

set()

on()

Comparison and containment

compare()

equals()

isBefore()

isAfter()

contains()

isPast()

isFuture()

isLeapYear()

Measuring spans

until()

since()

Formatting and conversion

format()

as()

toString()

toTemporal()

valueOf()

`YearMonth` class

`plus()`

`minus()`

`set()`

`on()`

`compare()`

`equals()`

`isBefore()`

`isAfter()`

`contains()`

`isPast()`

`isFuture()`

`isLeapYear()`

`until()`

`since()`

`format()`

`as()`

`toString()`

`toTemporal()`

`valueOf()`