native-dates

Plugins / Reference

tokens plugin

Token patterns like 'YYYY-MM-DD' in format(), plus localized month and weekday name lists.

import '@native-dates/plugins/tokens'0.8 kB min+br

Formatting with patterns

Import the plugin once to teach format() token patterns on core dates, datetimes, and times. All built-in preset names and Intl options objects continue working unchanged.

tokens.js
import '@native-dates/plugins/tokens';
import { date, datetime, time } from 'native-dates';

const standup = datetime('2026-11-16T09:30', 'America/Los_Angeles');

standup.format('YYYY-MM-DD'); // '2026-11-16'
standup.format('ddd, MMM D [at] h:mm A', 'en-US'); // 'Mon, Nov 16 at 9:30 AM'
standup.format('date', 'en-US'); // 'Nov 16, 2026'

Wrap literal words in square brackets so letters inside [at] copy verbatim. Pass a locale tag second to localize month, weekday, and zone names.

date('2026-09-06').format('dddd D MMMM', 'de'); // 'Sonntag 6 September'
time('17:30').format('[Closes at] h:mm a'); // 'Closes at 5:30 pm'

Token reference

Longer tokens match first, so MMMM always reads as the full month name.

Token Sample Description
YYYY '2026' Four-digit calendar year, zero-padded for years below 1000.
YY '26' Two-digit calendar year.
Q '4' Quarter of the year, from 1 through 4.
M, MM '9', '09' Month number from 1 through 12, unpadded or zero-padded.
MMM, MMMM 'Sep', 'September' Localized short or full month name from Intl.
D, DD '6', '06' Day of the month from 1 through 31, unpadded or zero-padded.
Do '6th' Day of the month with an English ordinal suffix.
dd, ddd, dddd 'Su', 'Sun', 'Sunday' Localized two-letter, short, or full weekday name.
W '36' ISO week number of the year, from 1 through 53.
H, HH '9', '09' 24-hour clock hour from 0 through 23, unpadded or zero-padded.
h, hh '9', '09' 12-hour clock hour from 1 through 12, unpadded or zero-padded.
m, mm '5', '05' Minute from 0 through 59, unpadded or zero-padded.
s, ss '4', '04' Second from 0 through 59, unpadded or zero-padded.
SSS '250' Three-digit millisecond, from 000 through 999.
A, a 'AM', 'am' Uppercase or lowercase meridiem marker.
Z, ZZ '-08:00', '-0800' Active UTC offset with a colon, or compact without a colon.
z, zzzz 'PST', 'Pacific Standard Time' Localized short or full time zone name at this instant.
X, x '1794850200', '1794850200000' Unix timestamp in whole seconds or milliseconds.
[text] 'at' Escaped literal characters copied straight into the output.

Each value type only formats fields it owns. A DateTime supports every token above, a calendar date supports calendar tokens from year through ISO week, and a time supports clock and meridiem tokens.

Missing fields throw instead of printing zeros

Formatting clock tokens on a CalendarDate or calendar tokens on a Time throws an error rather than inventing midnight or a dummy date. Combine them into a datetime first when a pattern needs both parts.

Methods and helpers

format()

dt.format(pattern, locale?): string
d.format(pattern, locale?): string
t.format(pattern, locale?): string

Extends core formatting so any string that is not a preset name is evaluated as a token pattern. Preset names and options objects pass straight through to Intl.DateTimeFormat.

Parameters

patternstring | FormatSpecdefault 'medium'

Token pattern such as 'YYYY-MM-DD', core preset name, or Intl options object.

localestring

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

Returns

string

Formatted string using the receiver's fields and time zone.

const launch = datetime('2026-09-06T14:30:00Z', 'America/New_York');

launch.format('YYYY-MM-DD HH:mm:ss z', 'en-US'); // '2026-09-06 10:30:00 EDT'

monthNames()

monthNames(style?, locale?): string[]

Returns all twelve month names from January through December in the given or configured locale, ready for dropdown menus and picker headers.

Parameters

style'long' | 'short'default 'long'

Full month names such as 'January' or abbreviated names such as 'Jan'.

localestring

BCP 47 locale tag overriding the configured default.

Returns

string[]

Fresh array of twelve localized month names.

import { monthNames } from '@native-dates/plugins/tokens';

monthNames('long', 'en-US').slice(0, 3); // ['January', 'February', 'March']
monthNames('short', 'fr').slice(0, 3); // ['janv.', 'févr.', 'mars']

weekdayNames()

weekdayNames(style?, firstDay?, locale?): string[]

Returns the seven weekday names rotated to begin on the given day or the configured week start, so a calendar header row matches startOf('week').

Parameters

style'short' | 'long'default 'short'

Short labels such as 'Mon' or full weekday names such as 'Monday'.

firstDayWeekday

Starting weekday name or ISO number, defaulting to the configured weekStart.

localestring

BCP 47 locale tag overriding the configured default.

Returns

string[]

Seven localized weekday names ordered from the start of the week.

import { weekdayNames } from '@native-dates/plugins/tokens';

weekdayNames('short', 'monday', 'en-US');
// ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
weekdayNames('long', 'sunday', 'de-DE')[0]; // 'Sonntag'
Edit this pageUpdated Nov 12, 2026