native-dates

API / Functions

date() function

Create a CalendarDate from an ISO date string, year-month-day numbers, fields, or the current day.

import { date, today } from 'native-dates'core 7.3 kB min+br

Reading calendar dates

date()

date(input, options?): CalendarDate
date(input, zone?): CalendarDate
date(year, month, day): CalendarDate

Creates a CalendarDate from an ISO date string, three 1-indexed numbers, a fields object, or an existing date or timestamp. Impossible dates such as February 30 throw a RangeError instead of rolling into March.

create.js
import { date, datetime } from 'native-dates';

const fromIso = date('2026-11-16');
const fromNumbers = date(2026, 11, 16);
const fromFields = date({ year: 2026, month: 11, day: 16 });
const fromMoment = date(datetime('2026-11-17T02:00:00Z', 'America/Los_Angeles'));

fromNumbers.toString(); // '2026-11-16'
fromMoment.toString(); // '2026-11-16'

Parameters

inputCalendarDateInput | numberrequired

ISO date string, fields object, existing date or timestamp, or the 4-digit year.

optionsZone | ReadOptions | number

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

3 options
zoneZone

Time zone used to determine the calendar day of a JavaScript Date or loose timestamp.

loosebooleandefault false

Parse informal date strings and return null on unreadable input with @native-dates/plugins/loose.

dayFirstboolean

Read numeric dates such as '07.09.2026' as day-first in loose mode.

daynumber

Day of the month from 1 to 31 when passing year, month, and day.

Returns

CalendarDate

A CalendarDate with no clock or zone, or null when loose mode cannot read input.

When reading a native JavaScript Date, pass a time zone to choose which location’s calendar day to extract:

const stamp = new Date('2026-11-17T02:00:00Z');

date(stamp, 'America/Los_Angeles').toString(); // '2026-11-16'
date(stamp, 'UTC').toString(); // '2026-11-17'

Accepted inputs

Months always run from 1 for January through 12 for December, unlike JavaScript’s zero-indexed Date constructor.

Input Example How it reads
ISO date string '2026-11-16' Reads the 4-digit year, 1-indexed month, and day directly.
Local date-time string '2026-11-16T09:30' Keeps the calendar date and drops the time of day.
Year, month, and day date(2026, 11, 16) Takes three whole numbers with 1 for January through 12 for December.
Fields object { year: 2026, month: 11, day: 16 } Reads 1-indexed calendar fields and rejects impossible dates.
DateTime datetime('2026-11-17T02:00Z', 'America/Los_Angeles') Extracts the calendar date in that instance’s own time zone.
JavaScript Date date(jsDate, 'America/Los_Angeles') Reads the calendar day of that timestamp in the given zone or configured default.
Temporal value Temporal.PlainDate, Temporal.ZonedDateTime Extracts the ISO calendar date.

Instant strings require a time zone

An ISO string with a trailing Z or UTC offset names a moment that can fall on two different calendar days around the world. Call datetime(text, zone).date to choose the time zone explicitly, or pass a zone in loose mode with @native-dates/plugins/loose.

Relative calendar days

Today’s date depends on where you stand on Earth. Each helper below accepts an optional time zone and falls back to your configured default.

today()

today(zone?): CalendarDate

Returns today’s calendar date in the given time zone or your configured default. Late in the evening in the Americas, Asia and Oceania have already crossed midnight into the next calendar date.

Parameters

zoneZone

Time zone whose current calendar date to read, such as 'Asia/Tokyo' or 'America/Los_Angeles'.

Returns

CalendarDate

Today's CalendarDate in zone.

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

const inLosAngeles = today('America/Los_Angeles');
const inTokyo = today('Asia/Tokyo');

// At 02:00 UTC on Nov 17, Los Angeles is still on Nov 16 while Tokyo is on Nov 17
const moment = '2026-11-17T02:00:00Z';
datetime(moment, 'America/Los_Angeles').date.toString(); // '2026-11-16'
datetime(moment, 'Asia/Tokyo').date.toString(); // '2026-11-17'

tomorrow()

tomorrow(zone?): CalendarDate

Returns tomorrow’s calendar date in the given time zone, one calendar day after today(zone).

Parameters

zoneZone

Time zone whose calendar to advance from today.

Returns

CalendarDate

Tomorrow's CalendarDate in zone.

import { tomorrow } from 'native-dates';

const nextDay = tomorrow();
const londonTomorrow = tomorrow('Europe/London');

yesterday()

yesterday(zone?): CalendarDate

Returns yesterday’s calendar date in the given time zone, one calendar day before today(zone).

Parameters

zoneZone

Time zone whose calendar to step back from today.

Returns

CalendarDate

Yesterday's CalendarDate in zone.

import { yesterday } from 'native-dates';

const priorDay = yesterday();
const londonYesterday = yesterday('Europe/London');
Edit this pageUpdated Nov 12, 2026