Skip to content
date-and-timedate-and-time

Plugins

See More

date-and-time adopts a plugin system. Special tokens used relatively infrequently are provided as plugins outside the main library. By adding plugins as needed, you can use those tokens in Formatter and Parser. Here, Formatter refers to the output engine used by the format function, and Parser refers to the parsing engine used by the parse, preparse, and isValid functions. These engines are extended by adding plugins as arguments to these functions.

Installation

import { format } from 'date-and-time';
import { formatter as foobar } from 'date-and-time/plugins/foobar';


format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar] });

CommonJS

const { format } = require('date-and-time');
const foobar = require('date-and-time/plugins/foobar');


format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar.formatter] });

Writing Your Own Plugin

For a quick, one-off token, you can pass a plain object literal instead of a plugin module. Annotate it with FormatterPluginObject (for format) or ParserPluginObject (for parse, preparse, and isValid), and any key that collides with a built-in token (such as YYYY or MM) is rejected at compile time.

import { format } from 'date-and-time';
import type { DateLike, FormatterPluginObject } from 'date-and-time/plugin';


const quarter: FormatterPluginObject = {
  Q: (d: DateLike) => String((d.getMonth() / 3 | 0) + 1)
};


format(new Date(2025, 3, 1), 'YYYY [Q]Q', { plugins: [quarter] });
// => 2025 Q2
// @ts-expect-error - `YYYY` is a built-in token and cannot be redefined this way
const invalid: FormatterPluginObject = { YYYY: () => 'nope' };

Parser plugins are more limited than formatter plugins. A formatter token can return any string, but a parser token can only supply one of the date components that the built-in parser already reads: year (Y), month (M), day (D), 24-hour (H), meridiem (A), 12-hour (h), minute (m), second (s), millisecond (S), and time zone offset (Z). There is no way to add a new component.

A parser token receives the remaining input string and returns a value, the length of the text it consumed, and the token naming the component that value is applied to. The exec helper builds this result from a regular expression, and its third argument is the component. A length of 0 means the token did not match, and parsing stops there. A result without a token only consumes its text and its value is discarded, which is how the day-of-week plugin skips a day name. Any name other than the components above is rejected by the type definitions and ignored at run time.

The following token reads a day with an English ordinal suffix, such as 23rd; the bundled ordinal plugin below provides the same token. The regular expression matches only the number, so length is increased by 2 to consume the suffix as well, while value is applied to the day component:

import { parse } from 'date-and-time';
import { exec } from 'date-and-time/plugin';
import type { ParserPluginObject } from 'date-and-time/plugin';


const ordinal: ParserPluginObject = {
  DDD: (str: string) => {
    const result = exec(/^\d\d?(?=st|nd|rd|th)/, str, 'D');


    if (result.length > 0) {
      result.length += 2;
    }
    return result;
  }
};


parse('August 23rd, 2025', 'MMMM DDD, YYYY', { plugins: [ordinal] });
// => Sat Aug 23 2025 00:00:00 GMT-0700

Objects passed to plugins without one of these annotations are not checked against built-in tokens. Since custom plugins are searched before the built-in tokens, a key such as YYYY in such an object silently overrides the built-in token. The FormatterPlugin and ParserPlugin types, which plugins also accepts, are deprecated, kept only for compatibility with existing code, and will be removed in the next major version.

day-of-week

This plugin adds tokens to the Parser for reading the day of the week. Since the day of the week does not provide information that identifies a specific date, it is a meaningless token, but it can be used to skip that portion when the string you want to read contains a day of the week.

Parser

Token Meaning Input Examples
dddd Full day name Friday, Sunday
ddd Short day name Fri, Sun
dd Very short day name Fr, Su 
import { parse } from 'date-and-time';
import { parser as day_of_week } from 'date-and-time/plugins/day-of-week';


parse(
  'Thursday, March 05, 2020', 'dddd, MMMM, D YYYY',
  { plugins: [day_of_week] }
);

microsecond

This plugin adds tokens to the Parser for reading microseconds. Since the precision of JavaScript’s Date type is milliseconds, these tokens are meaningless, but they can be used to skip that portion when the string you want to read contains microseconds.

Parser

Token Meaning Input Examples
SSSSSS 6-digit milliseconds 123456, 000001
SSSSS 5-digit milliseconds 12345, 00001
SSSS 4-digit milliseconds 1234, 0001
fff 3-digit microseconds 753, 022
ff 2-digit microseconds 75, 02
f 1-digit microseconds 7, 0 
import { parse } from 'date-and-time';
import { parser as microsecond } from 'date-and-time/plugins/microsecond';


parse('12:34:56.123456', 'HH:mm:ss.SSSSSS', { plugins: [microsecond] });
parse('12:34:56 123.456', 'HH:mm:ss SSS.fff', { plugins: [microsecond] });

nanosecond

This plugin adds tokens to the Parser for reading nanoseconds. Since the precision of JavaScript’s Date type is milliseconds, these tokens are meaningless, but they can be used to skip that portion when the string you want to read contains nanoseconds.

Parser

Token Meaning Input Examples
SSSSSSSSS 9-digit milliseconds 123456789, 000000001
SSSSSSSS 8-digit milliseconds 12345678, 00000001
SSSSSSS 7-digit milliseconds 1234567, 0000001
FFF 3-digit nanoseconds 753, 022
FF 2-digit nanoseconds 75, 02
F 1-digit nanoseconds 7, 0 
import { parse } from 'date-and-time';
import { parser as microsecond } from 'date-and-time/plugins/microsecond';
import { parser as nanosecond } from 'date-and-time/plugins/nanosecond';


parse(
  '12:34:56.123456789',
  'HH:mm:ss.SSSSSSSSS',
  { plugins: [microsecond, nanosecond] }
);


parse(
  '12:34:56 123456.789',
  'HH:mm:ss SSSSSS.FFF',
  { plugins: [microsecond, nanosecond] }
);

ordinal

This plugin adds tokens to the Formatter and Parser for outputting or reading ordinal representations of days. This ordinal representation is limited to English and is not supported for locales other than English.

Formatter

Token Meaning Output Examples
DDD Ordinal representation of day 1st, 2nd, 3rd 
import { format } from 'date-and-time';
import { formatter as ordinal } from 'date-and-time/plugins/ordinal';


format(new Date(), 'MMM DDD YYYY', { plugins: [ordinal] });
// => Jan 1st 2019

Parser

Token Meaning Input Examples
DDD Ordinal representation of day 1st, 2nd, 3rd 
import { parse } from 'date-and-time';
import { parser as ordinal } from 'date-and-time/plugins/ordinal';


parse('Jan 1st 2019', 'MMM DDD YYYY', { plugins: [ordinal] });

quarter

This plugin adds a token to the Formatter for outputting the quarter of the year.

Formatter

Token Meaning Output Examples
Q Quarter of year 1, 2, 3, 4 
import { format } from 'date-and-time';
import { formatter as quarter } from 'date-and-time/plugins/quarter';


format(new Date(2025, 0, 1), 'YYYY [Q]Q', { plugins: [quarter] });
// => 2025 Q1
format(new Date(2025, 9, 1), 'YYYY [Q]Q', { plugins: [quarter] });
// => 2025 Q4

timestamp

This plugin adds tokens to the Formatter for outputting Unix timestamps.

Formatter

Token Meaning Output Examples
t Unix timestamp (seconds) 0, 1000000000
T Unix timestamp (milliseconds) 0, 1000000000000 
import { format } from 'date-and-time';
import { formatter as timestamp } from 'date-and-time/plugins/timestamp';


format(new Date(1000000000000), 't', { plugins: [timestamp] });
// => 1000000000
format(new Date(1000000000000), 'T', { plugins: [timestamp] });
// => 1000000000000

two-digit-year

This plugin adds tokens to the Parser for reading 2-digit years. This token identifies years based on the following rules:

  • Values of 70 or above are interpreted as 1900s
  • Values of 69 or below are interpreted as 2000s

Parser

Token Meaning Input Examples
YY 2-digit year 90, 00, 08, 19 
import { parse } from 'date-and-time';
import { parser as two_digit_year } from 'date-and-time/plugins/two-digit-year';


parse('Dec 25 69', 'MMM DD YY', { plugins: [two_digit_year] });
// => Dec 25 2069
parse('Dec 25 70', 'MMM DD YY', { plugins: [two_digit_year] });
// => Dec 25 1970

week

This plugin adds tokens to the Formatter for outputting ISO week dates. These tokens follow the ISO 8601 week date system, where weeks start on Monday and the first week of the year is the one that contains the first Thursday.

Formatter

Token Meaning Output Examples
W ISO week number 1, 27, 53
WW ISO week number (zero-padded) 01, 27, 53
G ISO week year 2024, 2025
GG ISO week year (2-digit zero-padded) 24, 25
GGGG ISO week year (4-digit zero-padded) 2024, 2025 
import { format } from 'date-and-time';
import { formatter as week } from 'date-and-time/plugins/week';


format(new Date(2024, 0, 1), 'GGGG-[W]WW', { plugins: [week] });
// => 2024-W01


// Note: Dec 30, 2024 belongs to ISO week year 2025
format(new Date(2024, 11, 30), 'YYYY vs GGGG [W]W', { plugins: [week] });
// => 2024 vs 2025 W1

zonename

This plugin adds tokens to the Formatter for outputting timezone names. These timezone names are limited to English and are not supported for locales other than English.

Formatter

Token Meaning Output Examples
z Short timezone name PST, EST
zz Long timezone name Pacific Standard Time 
import { format } from 'date-and-time';
import { formatter as zonename } from 'date-and-time/plugins/zonename';


format(
  new Date(),
  'MMMM DD YYYY H:mm zz',
  { plugins: [zonename] }
);
// March 14 2021 1:59 Pacific Standard Time


format(
  new Date(),
  'MMMM DD YYYY H:mm z',
  { plugins: [zonename], timeZone: 'Asia/Tokyo' }
);
// March 14 2021 18:59 JST