formatDate

Learn how to use the formatDate function in Notion formulas.

The formatDate() function formats a date as a string using various formatting tokens.

formatDate(date, string [must conform to token format])

date.formatDate(string [must conform to token format])
Code language: JavaScript (javascript)

It accepts two arguments in the following order:

  1. A date (can be passed via properties – Date, Created Time, Last Edited Time – or via date functions such as now, fromTimestamp, dateAdd, dateSubtract)
  2. A string specifying the formatting tokens for the date output
formatDate(now(), "MMMM DD YYYY") /* Output: June 24 2022 */

now().formatDate("dddd, MMMM DD, YYYY hh:mm A zz")
/* Output: Friday, June 24, 2022 10:45 AM MDT */
Code language: JavaScript (javascript)

You can also use brackets ([]) to escape any characters that you’d like to render explicitly (i.e. not use a formatting command):

formatDate(now(), "[Month of] MMMM, YYYY") 
/* Output: Month of June, 2022 */
Code language: JavaScript (javascript)

By specifying the formatting options you want within the function’s second argument, you can customize your date format.

Notion uses Luxon to handle date formatting, but retains a lot of the tokens used by Luxon’s predecessor, Moment. Refer to the token lists below to see all possible formatting options.

formatDate() returns a string, not a date. Therefore, it is not possible to do date math on its output. You can however use parseDate and a date formatted as YYYY-MM-DD to do this.

Good to Remember: Notion formulas are picky about data types. The formula editor will almost never do automatic type conversion, so you must pass the correct data types when you use functions.

For example, you cannot use dateAdd or dateSubtract on the output of formatDate():

/* ERROR: Argument of type text does not satisfy function dateAdd. */
dateAdd(formatDate(now(),"MMMM DD YYYY"), 4, "months")

/* Using parseDate */
dateAdd(parseDate("2023-09-07"), 4, "months")
/* Output: January 7, 2024 */
Code language: JavaScript (javascript)

It is also very difficult to perform date comparisons using the output of formatDate(). While equality comparisons work well:

formatDate(now(), "MMM DD YYYY") == formatDate(prop("Date"), "MMM DD YYYY")
Code language: JavaScript (javascript)

…it is much more difficult to perform “earlier than” or “later than” comparisons.

Therefore, it is recommended to use functions such as timestamp, date, week, month, year, etc. to make these kinds of comparisons.

It is also not possible to create date-based filters in a database view using a formula property that outputs a date string via formatDate().

However, it is possible to work with the output of formatDate() using the Notion API.

For an example, see this recurring tasks tutorial that uses Make.com and the Notion API to parse the output of formatDate():

The Best Way to Create Recurring Tasks in Notion (2023)
Learn how to add recurring tasks to Notion and completely automate them (for free) in this step-by-step tutorial.
thomasjfrank.com

This example database shows the numbered week of year that matches the date in the Date property.

Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.
A new tool that blends your everyday work apps into one. It’s the all-in-one workspace for you and your team
thomasfrank.notion.site
formatDate(prop("Date"), "wo")
Code language: JavaScript (javascript)
formatDate(prop("Date"), "dddd, MMMM Do, YYYY, HH:mm A, wo [week of the year]")
Code language: JavaScript (javascript)
TokenDescriptionExample
AUppercase meridiemPM
aMeridiempm
HHour in 24-hour time, no padding4
HHHour in 24-hour time, padded to 204
hHour in 12-hour time, no padding4
hhHour in 12-hour time, padded to 204
k1-based hour in 24-hour time, no padding4
kk1-based hour in 24-hour time, padded to 204
mMinute, no padding8
mmMinute, padded to 208
sSecond, no padding *0
ssSecond, padded to 2 *00
SFractional seconds, between 0 and 9 *0
SSFractional seconds, between 0 and 99, padded to 2 *00
SSSFractional seconds, between 0 and 999, padded to 3 *000
LTLocalized 12-hour time (no padding), uppercase meridiem4:08 PM
LTSLocalized 12-hour time with seconds (no padding), uppercase meridiem *4:08:00 PM
* While these tokens do get parsed, Notion only displays time to the minute, so seconds will always be displayed as 0.
TokenDescriptionExample
DDay of month, no padding21
DoDay of month, with ordinal suffix21st
DDDay of month, padded to 221
DDDDay of year, no padding294
DDDoDay of year, with ordinal suffix294th
DDDDDay of year, padded to 3294
dZero-based day of week, no padding3
doZero-based day of week, with ordinal suffix3rd
ddLocalized day of week name, 2-letter abbreviationWe
dddLocalized day of week name, 3-letter abbreviationWed
ddddLocalized day of week name, unabbreviatedWednesday
EISO day of week, no padding3
eLocalized day of week, no padding3
TokenDescriptionExample
wWeek of year, no padding4
woWeek of year, with ordinal suffix4th
wwWeek of year, padded to 204
WISO week of year, no padding4
WoISO week of year, with ordinal suffix4th
WWISO week of year, padded to 204
TokenDescriptionExample
MMonth, no padding4
MoMonth, with ordinal suffix4th
MMMonth, padded to 204
MMMLocalized month name, 3-letter abbreviationOct
MMMMLocalized month name, unabbreviatedOctober
TokenDescriptionExample
QQuarter, no padding4
QoQuarter, with ordinal suffix4th
QQQuarter, padded to 204
TokenDescriptionExample
YISO year2015
YYYear, 2 digits15
YYYYYear, 4 digits2015
YYYYYYExpanded year+002015
ggWeek year, 2 digits15
ggggWeek year, 4 digits2015
GGISO week year, 2 digits15
GGGGISO week year, 4 digits2015
TokenDescriptionExample
XUnix timestamp1445468880
xUnix millisecond timestamp1445468880000
TokenDescriptionExample
ZTime zone, short offset-07:00
ZZTime zone, techie offset-0700
ZZZTime zone, unabbreviated named offsetPacific Daylight Time
TokenDescriptionExample
LLocalized month (padded to 2), day of month (padded to 2), year (4 digits)10/21/2015
lLocalized month (no padding), day of month (no padding), year (4-digits)10/21/2015
LLLocalized month name (unabbreviated), day of month (no padding), year (4-digits)October 21, 2015
llLocalized month name (3-letter abbreviation), day of month (no padding), year (4-digits)Oct 21, 2015
LLLLocalized month name (unabbreviated), day of month (no padding), year (4-digits), 12-hour time (no padding), uppercase meridiemOctober 21, 2015 4:08 PM
lllLocalized month name (3-letter abbreviation), day of month (no padding), year (4-digits), 12-hour time (no padding), uppercase meridiemOct 21, 2015 4:08 PM
LLLLLocalized day of week name (unabbreviated), month name (unabbreviated), day of month (no padding), year (4-digits), time (no padding)Wednesday, October 21, 2015 4:08 PM
llllLocalized day of week name (3-letter abbreviation), month name (3-letter abbreviation), day of month (no padding), year (4-digits), time (no padding)Wed, Oct 21, 2015 4:08 PM
TokenDescriptionExample
[Great Scott!]Escaped characters (between square brackets)Great Scott!
About the Author

My name is Thomas Frank, and I'm a Notion-certified writer, YouTuber, and template creator. I've been using Notion since 2018 to organize my personal life and to run my business and YouTube channel. In addition to this formula reference, I've created a free Notion course for beginners and several productivity-focused Notion templates. If you'd like to connect, follow me on Twitter.

🤔 Have an UB Question?

Fill out the form below and I’ll answer as soon as I can! ~Thomas

🤔 Have a Question?

Fill out the form below and I’ll answer as soon as I can! ~Thomas