Function format

Description

Return the formatted date string in the given format. The result may vary by locale.

⚠️ Please note that the format tokens differ from Moment.js and other libraries. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

The characters wrapped between two single quotes characters (') are escaped. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote. (see the last example)

Format of the string is based on Unicode Technical Standard #35: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table with a few additions (see note 7 below the table).

Accepted patterns:

1. "Formatting" units (e.g. formatting quarter) in the default en-US locale are the same as "stand-alone" units, but are different in some languages. "Formatting" units are declined according to the rules of the language in the context of a date. "Stand-alone" units are always nominative singular:

   format(new Date(2017, 10, 6), 'do LLLL', {locale: cs}) //=> '6. listopad'

   format(new Date(2017, 10, 6), 'do MMMM', {locale: cs}) //=> '6. listopadu'

2. Any sequence of the identical letters is a pattern, unless it is escaped by the single quote characters (see below). If the sequence is longer than listed in table (e.g. EEEEEEEEEEE) the output will be the same as default pattern for this unit, usually the longest one (in case of ISO weekdays, EEEE). Default patterns for units are marked with "2" in the last column of the table.

   format(new Date(2017, 10, 6), 'MMM') //=> 'Nov'

   format(new Date(2017, 10, 6), 'MMMM') //=> 'November'

   format(new Date(2017, 10, 6), 'MMMMM') //=> 'N'

   format(new Date(2017, 10, 6), 'MMMMMM') //=> 'November'

   format(new Date(2017, 10, 6), 'MMMMMMM') //=> 'November'

3. Some patterns could be unlimited length (such as yyyyyyyy). The output will be padded with zeros to match the length of the pattern.

   format(new Date(2017, 10, 6), 'yyyyyyyy') //=> '00002017'

4. QQQQQ and qqqqq could be not strictly numerical in some locales. These tokens represent the shortest form of the quarter.

5. The main difference between y and u patterns are B.C. years:

   Year	y	u
   AC 1	1	1
   BC 1	1	0
   BC 2	2	-1

   Also yy always returns the last two digits of a year, while uu pads single digit years to 2 characters and returns other years unchanged:

   Year	yy	uu
   1	01	01
   14	14	14
   376	76	376
   1453	53	1453

   The same difference is true for local and ISO week-numbering years (Y and R), except local week-numbering years are dependent on options.weekStartsOn and options.firstWeekContainsDate (compare getISOWeekYear and getWeekYear).

6. Specific non-location timezones are currently unavailable in date-fns, so right now these tokens fall back to GMT timezones.

7. These patterns are not in the Unicode Technical Standard #35:

   • i: ISO day of week
   • I: ISO week of year
   • R: ISO week-numbering year
   • t: seconds timestamp
   • T: milliseconds timestamp
   • o: ordinal number modifier
   • P: long localized date
   • p: long localized time

8. YY and YYYY tokens represent week-numbering years but they are often confused with years. You should enable options.useAdditionalWeekYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md

9. D and DD tokens represent days of the year but they are often confused with days of the month. You should enable options.useAdditionalDayOfYearTokens to use them. See: https://github.com/date-fns/date-fns/blob/master/docs/unicodeTokens.md