format()

Formats a Date object according to the specified format string.

Syntax

format(dateObj, formatString[, options])

Parameters

Parameter	Type	Required	Description
`dateObj`	`Date`	Yes	The Date object to format
`formatString`	`string \| CompiledObject`	Yes	The format string or compiled object
`options`	`FormatterOptions`	No	Formatter options for customization

Returns

string - The formatted date string

Basic Examples

import { format } from 'date-and-time';

const now = new Date();

format(now, 'YYYY/MM/DD HH:mm:ss');
// => 2025/08/23 14:30:45

format(now, 'ddd, MMM DD YYYY');
// => Sat, Aug 23 2025

format(now, 'hh:mm A [GMT]Z');
// => 02:30 PM GMT-0700

Format Tokens

Date Tokens

Token	Description	Output Examples
`YYYY`	4-digit year	0999, 2015
`YY`	2-digit year	99, 01, 15
`Y`	Year without zero padding	2, 44, 888, 2015
`MMMM`	Full month name	January, December
`MMM`	Short month name	Jan, Dec
`MM`	Month (01-12)	01, 12
`M`	Month without zero padding	1, 12
`DD`	Day (01-31)	02, 31
`D`	Day without zero padding	2, 31

Day of Week Tokens

Token	Description	Output Examples
`dddd`	Full day name	Friday, Sunday
`ddd`	Short day name	Fri, Sun
`dd`	Very short day name	Fr, Su

Time Tokens

Token	Description	Output Examples
`HH`	Hour in 24-hour format	23, 08
`H`	Hour in 24-hour format without zero padding	23, 8
`hh`	Hour in 12-hour format	11, 08
`h`	Hour in 12-hour format without zero padding	11, 8
`mm`	Minutes	14, 07
`m`	Minutes without zero padding	14, 7
`ss`	Seconds	05, 10
`s`	Seconds without zero padding	5, 10
`SSS`	3-digit milliseconds	753, 022
`SS`	2-digit milliseconds	75, 02
`S`	1-digit milliseconds	7, 0

AM/PM Tokens

Token	Description	Output Examples
`A`	Uppercase AM/PM	AM, PM
`AA`	Uppercase AM/PM (with periods)	A.M., P.M.
`a`	Lowercase AM/PM	am, pm
`aa`	Lowercase AM/PM (with periods)	a.m., p.m.

Timezone Tokens

Token	Description	Output Examples
`Z`	Timezone offset	+0100, -0800
`ZZ`	Timezone offset with colon	+01:00, -08:00

Plugin Tokens

Additional tokens available with plugins:

Token	Description	Output Examples	Plugin Required
`DDD`	Ordinal representation	1st, 2nd, 3rd	ordinal
`Q`	Quarter of year	1, 2, 3, 4	quarter
`t`	Unix timestamp (seconds)	0, 1000000000	timestamp
`T`	Unix timestamp (milliseconds)	0, 1000000000000	timestamp
`W`	ISO week number	1, 27, 53	week
`WW`	ISO week number (zero-padded)	01, 27, 53	week
`G`	ISO week year	2024, 2025	week
`GG`	ISO week year (2-digit zero-padded)	24, 25	week
`GGGG`	ISO week year (4-digit zero-padded)	2024, 2025	week
`z`	Short timezone name	PST, EST	zonename
`zz`	Long timezone name	Pacific Standard Time	zonename

For available plugins, see the plugins option in FormatterOptions.

FormatterOptions

The FormatterOptions object allows you to customize the formatting behavior:

interface FormatterOptions {
  locale?: Locale;
  timeZone?: TimeZone | string;
  numeral?: Numeral;
  calendar?: 'gregory' | 'buddhist';
  hour12?: 'h11' | 'h12';
  hour24?: 'h23' | 'h24';
  plugins?: (FormatterPluginObject | FormatterPlugin)[];
}

locale

Type: Locale
Default: en (English)

Specifies the locale for localized formatting of month names, day names, and meridiem indicators.

import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';
import es from 'date-and-time/locales/es';

const date = new Date();

// Japanese formatting
format(date, 'YYYY年M月D日(ddd)', { locale: ja });
// => 2025年8月23日(土)

// Spanish formatting
format(date, 'dddd, D [de] MMMM [de] YYYY', { locale: es });
// => sábado, 23 de agosto de 2025

For a complete list of all supported locales with import examples, see Supported Locales.

timeZone

Type: TimeZone | string
Default: undefined (local timezone)

Converts the date to the specified timezone before formatting.

import { format } from 'date-and-time';

const date = new Date();

format(date, 'YYYY-MM-DD HH:mm:ss [JST]', { timeZone: 'Asia/Tokyo' });
// => 2025-08-23 23:30:45 JST

format(date, 'YYYY-MM-DD HH:mm:ss [EST]', { timeZone: 'America/New_York' });
// => 2025-08-23 09:30:45 EST

format(date, 'YYYY-MM-DD HH:mm:ss [UTC]', { timeZone: 'UTC' });
// => 2025-08-23 14:30:45 UTC

For a complete list of all supported timezones, see Supported Timezones.

numeral

Type: Numeral
Default: latn (Latin numerals)

Specifies the numeral system for formatting numbers.

import { format } from 'date-and-time';
import arab from 'date-and-time/numerals/arab';
import beng from 'date-and-time/numerals/beng';

const date = new Date();

// Arabic-Indic numerals
format(date, 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥

// Bengali numerals
format(date, 'DD/MM/YYYY', { numeral: beng });
// => ০৮/০৭/২০২৫

Available numeral systems:

latn - Latin numerals (0-9) - default
arab - Arabic-Indic numerals (٠-٩)
arabext - Extended Arabic-Indic numerals (۰-۹)
beng - Bengali numerals (০-৯)
mymr - Myanmar numerals (၀-၉)

calendar

Type: "gregory" | "buddhist"
Default: "gregory"

Specifies the calendar system for date calculations.

import { format } from 'date-and-time';

const date = new Date();

// Gregorian calendar (default)
format(date, 'MMMM D, YYYY');
// => August 23, 2025

// Buddhist calendar (543 years ahead)
format(date, 'MMMM D, YYYY', { calendar: 'buddhist' });
// => August 23, 2568

hour12

Type: "h11" | "h12"
Default: "h12"

Controls the 12-hour format interpretation. Use h11 for 11-hour format (0-11) or h12 for 12-hour format (1-12).

import { format } from 'date-and-time';

const midnight = new Date(2025, 7, 23, 0, 30, 0); // 12:30 AM

// h12 format (1-12)
format(midnight, 'h:mm A', { hour12: 'h12' });
// => 12:30 AM

// h11 format (0-11)
format(midnight, 'h:mm A', { hour12: 'h11' });
// => 0:30 AM

hour24

Type: "h23" | "h24"
Default: "h23"

Controls the 24-hour format interpretation. Use h23 for 23-hour format (0-23) or h24 for 24-hour format (1-24).

import { format } from 'date-and-time';

const midnight = new Date(2025, 7, 23, 0, 30, 0);

// h23 format (0-23)
format(midnight, 'H:mm', { hour24: 'h23' });
// => 0:30

// h24 format (1-24)
format(midnight, 'H:mm', { hour24: 'h24' });
// => 24:30

plugins

Type: (FormatterPluginObject | FormatterPlugin)[]
Default: undefined

Enables additional format tokens provided by plugins. Plugins extend the formatter with special tokens that are not included in the core library. Each entry may also be a plain object literal annotated with FormatterPluginObject, which rejects keys that collide with built-in tokens at compile time. Entries that are not annotated this way are not checked, so an entry that defines a built-in token such as YYYY overrides it. FormatterPlugin is deprecated, kept only for compatibility with existing code, and will be removed in the next major version. See the Plugins guide for details.

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

const date = new Date();

// Use ordinal plugin
format(date, 'MMMM DDD, YYYY', { plugins: [ordinal] });
// => August 23rd, 2025

// Use zonename plugin
format(date, 'YYYY-MM-DD HH:mm z', { plugins: [zonename] });
// => 2025-08-23 14:30 PDT

// Use multiple plugins together
format(date, 'MMMM DDD, YYYY h:mm A zz', { plugins: [ordinal, zonename] });
// => August 23rd, 2025 2:30 PM Pacific Daylight Time

For a complete list of available plugins, see Plugins.

Advanced Usage

Comments in Format Strings

Parts of the format string enclosed in square brackets are output literally:

import { format } from 'date-and-time';

const date = new Date();

format(date, '[Today is] dddd, MMMM D, YYYY');
// => Today is Saturday, August 23, 2025

format(date, 'YYYY-MM-DD[T]HH:mm:ss[Z]');
// => 2025-08-23T14:30:45Z

format(date, '[Report generated on] YYYY/MM/DD [at] HH:mm');
// => Report generated on 2025/08/23 at 14:30

// Escape square brackets to output them literally
format(date, '\\[YYYY-MM-DD HH:mm:ss\\]');
// => [2025-08-23 14:30:45]

Complex Localized Formatting

import { format } from 'date-and-time';
import ja from 'date-and-time/locales/ja';

const date = new Date();

format(date, 'YYYY年MMMM月D日dddd Ah:mm:ss [GMT]Z', {
  timeZone: 'Asia/Tokyo',
  locale: ja
});
// => 2025年8月23日土曜日 午後11:30:45 GMT+0900

Business and Technical Formats

import { format } from 'date-and-time';

const date = new Date();

// ISO 8601 format
format(date, 'YYYY-MM-DD[T]HH:mm:ss.SSS[Z]', { timeZone: 'UTC' });
// => 2025-08-23T14:30:45.123Z

// RFC 2822 format
format(date, 'ddd, DD MMM YYYY HH:mm:ss ZZ');
// => Sat, 23 Aug 2025 14:30:45 +09:00

// Log timestamp
format(date, '\\[YYYY-MM-DD HH:mm:ss.SSS\\]');
// => [2025-08-23 14:30:45.123]

// File naming
format(date, 'YYYYMMDD_HHmmss');
// => 20250823_143045

Performance Considerations

For repeated formatting with the same pattern, use compile() to precompile the format string:

import { format, compile } from 'date-and-time';

// Compile once
const pattern = compile('YYYY-MM-DD HH:mm:ss');

// Reuse for better performance
const dates = [new Date(), new Date(), new Date()];
dates.forEach(date => {
  console.log(format(date, pattern));
});