• type: h11 | h12
• default: h12
• The hour format to use for formatting. This is used when the hour is in 12-hour format. It can be h11 for 11-hour format or h12 for 12-hour format.

format(now, 'dddd, MMMM D, YYYY [at] h:mm:ss.SSS A [GMT]ZZ', { hour12: 'h11' });
// Wednesday, July 23, 2025 at 0:12:54.814 AM GMT-07:00

• type: h23 | h24
• default: h23
• The hour format to use for formatting. This is used when the hour is in 24-hour format. It can be h23 for 23-hour format or h24 for 24-hour format.

format(now, 'dddd, MMMM D, YYYY [at] H:mm:ss.SSS [GMT]ZZ', { hour24: 'h24' });
// => Wednesday, July 23, 2025 at 24:12:54.814 GMT-07:00

• type: Numeral
• default: latn
• The numeral system to use for formatting numbers. This is an object that provides methods to encode and decode numbers in the specified numeral system.

import arab from 'date-and-time/numerals/arab';

format(now, 'DD/MM/YYYY', { numeral: arab });
// => ٠٨/٠٧/٢٠٢٥

Currently, the following numeral systems are supported:

• arab
• arabext
• beng
• latn
• mymr

• type: buddhist | gregory
• default: gregory
• The calendar system to use for formatting dates. This can be buddhist for Buddhist calendar or gregory for Gregorian calendar.

format(now, 'dddd, MMMM D, YYYY', { calendar: 'buddhist' });
// => Wednesday, July 23, 2568

• type: TimeZone | UTC
• default: undefined
• The time zone to use for formatting dates and times. This can be a specific time zone object or UTC to use Coordinated Universal Time. If not specified, it defaults to undefined, which means the local time zone will be used.

import New_York from 'date-and-time/timezones/America/New_York';

format(now, 'dddd, MMMM D, YYYY [at] H:mm:ss.SSS [GMT]ZZ', { timeZone: New_York });
// => Wednesday, July 23, 2025 at 3:28:27.443 GMT-04:00

• type: Locale
• default: en
• The locale to use for formatting dates and times. This is an object that provides methods to get localized month names, day names, and meridiems.

import es from 'date-and-time/locales/es';

format(now, 'dddd, D [de] MMMM [de] YYYY, h:mm:ss.SSS aa [GMT]ZZ', { locale: es });
// => miércoles, 23 de julio de 2025, 12:38:08,533 a.m. GMT-07:00

Parts of the format string enclosed in brackets are output as-is, regardless of whether they are valid tokens.

format(new Date(), 'DD-[MM]-YYYY');     // => '02-MM-2015'
format(new Date(), '[DD-[MM]-YYYY]');   // => 'DD-[MM]-YYYY'

To output date and time as UTC timezone, specify the string UTC in the timeZone property of FormatterOptions.

format(new Date(), 'hh:mm A [GMT]Z');
// => '12:14 PM GMT-0700'

format(new Date(), 'hh:mm A [GMT]Z', { timeZone: 'UTC' });
// => '07:14 AM GMT+0000'

• type: h11 | h12
• default: h12
• The hour format to use for parsing. This is used when the hour is in 12-hour format. It can be h11 for 11-hour format (0 - 11) or h12 for 12-hour format (1 - 12).

parse('0:12:54 PM', 'h:mm:ss A', { hour12: 'h11' });
// => Jan 01 1970 12:12:54 GMT-0800

• type: h23 | h24
• default: h23
• The hour format to use for parsing. This is used when the hour is in 24-hour format. It can be h23 for 23-hour format (0 - 23) or h24 for 24-hour format (1 - 24).

parse('24:12:54', 'h:mm:ss', { hour24: 'h24' });
// => Jan 01 1970 00:12:54 GMT-0800

• type: Numeral
• default: latn
• The numeral system to use for parsing numbers. This is an object that provides methods to encode and decode numbers in the specified numeral system.

import arab from 'date-and-time/numerals/arab';

parse('٠٨/٠٧/٢٠٢٥', 'DD/MM/YYYY', { numeral: arab });
// => July 09 2025 00:00:00 GMT-0700

Currently, the following numeral systems are supported:

• arab
• arabext
• beng
• latn
• mymr

• type: buddhist | gregory
• default: gregory
• The calendar system to use for parsing dates. This can be buddhist for Buddhist calendar or gregory for Gregorian calendar.

parse('July 09 2025', 'MMMM DD YYYY', { calendar: 'buddhist' });
// => July 09 1482 00:00:00 GMT-0752
// Note: Buddhist calendar is 543 years ahead of Gregorian calendar,
// so 2025 BE (Buddhist Era) equals 1482 CE (Common Era)

• type: boolean
• default: false
• Whether to ignore case when matching strings. This is useful for matching month names, day names, and meridiems in a case-insensitive manner. If true, the parser will convert both the input string and the strings in the locale to lowercase before matching.

parse('july 09 2025', 'MMMM DD YYYY', { ignoreCase: true });
// => July 09 2025 00:00:00 GMT-0700

• type: TimeZone | UTC
• default: undefined
• The time zone to use for parsing dates and times. This can be a specific time zone object or UTC to use Coordinated Universal Time. If not specified, it defaults to undefined, which means the local time zone will be used.

import New_York from 'date-and-time/timezones/America/New_York';

parse('July 09 2025, 12:34:56', 'MMMM D YYYY, H:mm:ss', { timeZone: New_York });
// => July 09 2025 09:34:56 GMT-0700 (July 09 2025 12:34:56 GMT-0400)

parse('July 09 2025, 12:34:56', 'MMMM D YYYY, H:mm:ss', { timeZone: 'UTC' });
// => July 09 2025 05:34:56 GMT-0700 (July 09 2025 12:34:56 GMT+0000)

• type: Locale
• default: en
• The locale to use for parsing dates and times. This is an object that provides methods to get localized month names, day names, and meridiems.

import es from 'date-and-time/locales/es';

parse(
  '23 de julio de 2025, 12:38:08,533 a.m. GMT-07:00',
  'D [de] MMMM [de] YYYY, h:mm:ss,SSS aa [GMT]ZZ',
  { locale: es }
);
// => July 23 2025 12:38:08.533 GMT-0700

If this function fails to parse, it will return Invalid Date. Notice that the Invalid Date is a Date object, not NaN or null. You can tell whether the Date object is invalid as follows:

const today = parse('Jam 1 2017', 'MMM D YYYY');

if (isNaN(today.getTime())) {
  console.error('Parsing failed');
}

If the dateString does not contain a timezone offset and the timeZone property of the third argument is not specified, this function considers the dateString to be in the local timezone. If you want to process a dateString without a timezone offset as UTC timezone, set the string UTC to the timeZone property in the third argument. Note that the timezone offset contained in the dateString takes precedence over the timeZone property of the third argument.

parse('11:14:05 PM', 'hh:mm:ss A');
// => Jan 1 1970 23:14:05 GMT-0800

parse('11:14:05 PM GMT+0000', 'hh:mm:ss A [GMT]Z');
// => Jan 1 1970 23:14:05 GMT+0000

parse('11:14:05 PM', 'hh:mm:ss A', { timeZone: 'UTC' });
// => Jan 1 1970 23:14:05 GMT+0000

Default date is January 1, 1970, time is 00:00:00.000. Any date/time components not specified in the input string will be filled with these default values.

parse('11:14:05 PM', 'hh:mm:ss A');
// => Jan 1 1970 23:14:05 GMT-0800

parse('Feb 2000', 'MMM YYYY');
// => Feb 1 2000 00:00:00 GMT-0800

The parsable maximum date is December 31, 9999, and the minimum date is January 1, 0001.

parse('Dec 31 9999', 'MMM D YYYY');
// => Dec 31 9999 00:00:00 GMT-0800

parse('Dec 31 10000', 'MMM D YYYY');
// => Invalid Date

parse('Jan 1 0001', 'MMM D YYYY');
// => Jan 1 0001 00:00:00 GMT-0800

parse('Jan 1 0000', 'MMM D YYYY');
// => Invalid Date

If you use the hh or h (12-hour) token, use it together with the A (meridiem) token to get the correct value.

parse('11:14:05', 'hh:mm:ss');
// => Jan 1 1970 11:14:05 GMT-0800

parse('11:14:05 PM', 'hh:mm:ss A');
// => Jan 1 1970 23:14:05 GMT-0800

Any part of the given format string that you do not want to be recognized as a token should be enclosed in square brackets. They are considered comments and will not be parsed.

parse('12 hours 34 minutes', 'HH hours mm minutes');
// => Invalid Date

parse('12 hours 34 minutes', 'HH [hours] mm [minutes]');
// => Jan 1 1970 12:34:00 GMT-0800

Whitespace acts as a wildcard token. This token will skip parsing the corresponding parts of the date and time strings. This behavior is similar to enclosing part of a format string in square brackets (Token invalidation), but with the flexibility that the contents do not have to match exactly - only the character count needs to match between the format string and input string.

// This will be an error.
parse('2015/01/02 11:14:05', 'YYYY/MM/DD');
// => Invalid Date

parse('2015/01/02 11:14:05', 'YYYY/MM/DD         ');
// => Jan 2 2015 00:00:00 GMT-0800

... token ignores subsequent corresponding date and time strings. Use this token only at the end of a format string. The above example can also be written like this:

parse('2015/01/02 11:14:05', 'YYYY/MM/DD...');
// => Jan 2 2015 00:00:00 GMT-0800

This method calculates the number of days in the duration and returns a descriptor that includes the value in days, a format method for custom formatting, and a toParts method that returns an object with the parts of the duration.

duration.toDays().value;
// => 1.127835...

duration.toDays().format('D[day], H:mm:ss.SSSfffFFF');
// => 1day, 3:04:05.006000000

duration.toDays().toParts();
// => { days: 1, hours: 3, minutes: 4, seconds: 5, ... }

This method calculates the number of hours in the duration and returns a descriptor that includes the value in hours, a format method for custom formatting, and a toParts method that returns an object with the parts of the duration.

duration.toHours().value;
// => 27.068057...

duration.toHours().format('H:mm:ss.SSSfffFFF');
// => 27:04:05.006000000

duration.toHours().toParts();
// => { hours: 27, minutes: 4, seconds: 5, ... }

This method calculates the number of minutes in the duration and returns a descriptor that includes the value in minutes, a format method for custom formatting, and a toParts method that returns an object with the parts of the duration.

duration.toMinutes().value;
// => 1624.083433...

duration.toMinutes().format('m[min] ss.SSSfffFFF');
// => 1624min 05.006000000

duration.toMinutes().toParts();
// => { minutes: 1624, seconds: 5, milliseconds: 6, ... }

This method calculates the number of seconds in the duration and returns a descriptor that includes the value in seconds, a format method for custom formatting, and a toParts method that returns an object with the parts of the duration.

duration.toSeconds().value;
// => 97445.006

duration.toSeconds().format('s[sec] SSSfffFFF');
// => 97445sec 006000000

duration.toSeconds().toParts();
// => { seconds: 97445, milliseconds: 6, microseconds: 0, ... }

This method calculates the number of milliseconds in the duration and returns a descriptor that includes the value in milliseconds, a format method for custom formatting, and a toParts method that returns an object with the parts of the duration.

duration.toMilliseconds().value;
// => 97445006

duration.toMilliseconds().format('S.fffFFF');
// => 97445006.000000

duration.toMilliseconds().toParts();
// => { milliseconds: 97445006, microseconds: 0, nanoseconds: 0 }

This method calculates the number of microseconds in the duration and returns a descriptor that includes the value in microseconds, a format method for custom formatting, and a toParts method that returns an object with the microseconds and nanoseconds parts.

duration.toMicroseconds().value;
// => 97445006000

duration.toMicroseconds().format('f.FFF');
// => 97445006000.000

duration.toMicroseconds().toParts();
// => { microseconds: 97445006000, nanoseconds: 0 }

This method calculates the number of nanoseconds in the duration and returns a descriptor that includes the value in nanoseconds, a format method for custom formatting, and a toParts method that returns an object with the nanoseconds part.

duration.toNanoseconds().value;
// => 97445006000000

duration.toNanoseconds().format('F[ns]');
// => 97445006000000ns

duration.toNanoseconds().toParts();
// => { nanoseconds: 97445006000000 }

• formatString
  • type: string
  • The format string to use for formatting
• [numeral]
  • type: Numeral
  • default: latn
  • Optional numeral object for number formatting

The tokens available for use in the format string specified as the first argument and their meanings are as follows. However, tokens for units larger than the DurationDescriptor cannot be used. For example, in the case of a DurationDescriptor obtained by the toHours method, the D token representing days cannot be used. For a DurationDescriptor obtained by the toNanoseconds method, only the F token representing nanoseconds can be used.

What makes the format string in DurationDescriptor different from others is that repeating the same token produces a zero-padding effect. For example, formatting 1 day with DDDD results in an output of 0001.

When the value becomes negative, there are slight differences in the output results of the format method and the toParts method. In the format method, only the largest unit in the DurationDescriptor, for example, only the D token in the case of a DurationDescriptor obtained by the toDays method, gets a minus sign, while in the toParts method, all units get a minus sign.

duration.toDays().value;
// => -1.127835...

duration.toDays().format('D[day], H:mm:ss.SSSfffFFF');
// => -1day, 3:04:05.006000000

duration.toDays().toParts();
// => { days: -1, hours: -3, minutes: -4, seconds: -5, ... }

The format method may output -0. For example, when the value of a DurationDescriptor obtained by the toDays method is a negative decimal less than 1, using the D token in the format method outputs -0.

duration.toDays().value;
// => -0.127835...

duration.toDays().format('D[day], H:mm:ss.SSSfffFFF');
// => -0day, 3:04:05.006000000

duration.toDays().toParts();
// => { days: 0, hours: -3, minutes: -4, seconds: -5, ... }