Today, Notion introduced the biggest update of the year – Formulas 2.0. The Formulas 1.0 language and editor has been completely overhauled, making Notion formulas more powerful, and easier to write and edit. I will outline the major changes and the benefits, as well as share a comprehensive reference guide to help you get up to speed with Formulas 2.0 more quickly. Grab a copy of the template at the bottom of the page.
Disclaimer: As with many changes this may seem really scary at first, but understanding will come with time, so don’t panic and remember to have fun!
What’s new in 2.0
New language
- Expanded language functions more like JavaScript
- Gives us the ability to search, access, and manipulate data in a list. Note that data groupings are referred to in the documentation as “lists”, but those already familiar with programming will recognize them as “arrays”
- Gives us the ability to access and evaluate properties on related records, which can eliminate the need for many rollups
- Supports rich data outputs for Links, Pages, Blocks, and People
- Supports chaining multiple functions on one object using dot notation
- Existing 1.0 formulas will automatically convert to be compatible with 2.0
Improved formula editor
- Expandable multi-line editing makes it easier to view and edit long formulas
- Supports type-checking, error highlighting, and commenting
- Live preview within the editor
- Supports both light and dark mode
New Notion formula code block
- It’s now possible to script lengthy or complicated formulas in a Notion code block and then copy / paste into the formula editor
Notable changes and additions:
prop()
Status: changed
Previously, property values were retrieved by calling prop("Name"). In 2.0, values are retrieved using property tokens. Property tokens are created in one of three ways:
- Clicking on the property name in the selection list within the formula editor – a token will be created
- Typing
prop(”Name”)into the formula editor – the property will be converted into a token - Pasting
prop(”Name”)into the formula editor – the property will be converted into a token
When a token is created, you will recognize it because the background shading will turn grey.
slice()
Status: changed
Those who use formula generated progress bars will be familiar with the function slice() to extract a substring from a larger string of text. In 2.0, slice now operates on lists instead of strings. For functionality equal to slice from 1.0, you may now use the new function substring(), which works on strings in the same way!
Existing formulas using slice() will automatically be converted to use substring().
Example:
1.0 progress bar formula using slice
slice("▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒", 0, round(prop("Progress Percentage") * 10)) + " " + format(round(prop("Progress Percentage") * 100)) + "%"2.0 progress bar formula using substring
((substring("▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒", 0, round(prop("Progress Percentage") * 10)) + " ") + format(round(prop("Progress Percentage") * 100))) + "%"start(), end()
Status: changed
The functions start() and end() to access starting and ending dates from a date range have been renamed to dateStart() and dateEnd().
Existing formulas using start() and end() will automatically be converted to use dateStart() and dateEnd().
day()
Status: changed
Previously, the function day() returned the numerical day of the week from 0-6 (0=Sunday, 1=Monday, 2=Tuesday…) with the week beginning on Sunday. In 2.0, day() now returns values from 1-7 with the week beginning on Monday.
Note that formatDate(date, "d") will still return 0-6 with the week beginning on Sunday.
month()
Status: changed
Previously, the function month() returned the numerical month of the year from 0-11 (0=January, 1=February, 2=March…). In 2.0, month() now returns values 1-12.
parseDate()
Status: new
You may be familiar with the complexities involved in converting a string date into a usable date object in Notion. Now using the parseDate() function we are able to take a date string formatted according to the ISO 8601 standard and easily convert it into a usable date object. The output will be respected as a date, and can be grouped, filtered, or sorted as a date and will appear in calendar or timeline views.
Example: parseDate("2023-02-19T13:30Z") = @February 19, 2023 6:30 AM
upper()
Status: new
This new function converts a string of characters into uppercase.
Example: upper("notion") = “NOTION”
lower()
Status: new
This new function converts a string of characters into lowercase.
Example: lower("NoTiOn") = “notion”
style()
Status: new
Previously, there was no way to format your formula text output. In 2.0, we now have the style() function to add formatting to text!
Valid formatting styles: “b” (bold), “u” (underline), “i” (italics), “c” (code), or “s” (strikethrough). Valid colors: “gray”, “brown”, “orange”, “yellow”, “green”, “blue”, “purple”, “pink”, and “red”. Add “_background” to colors to set background colors.
Example: "This is " + style("purple and underlined", "purple", "purple_background", "b", "u") = “This is purple and underlined“
unstyle()
Status: new
Similar to style(), the unstyle() function removes one or all formatting styles from text output.
Example: unstyle("This is some bold red text", "red") = “This is some bold red text“
repeat()
Status: new
The new function repeat() will repeat a text string a given number of times. Combine it with the style function to create visual dividers or progress bars!
Example: repeat(join([style("★", "blue"), style("★", "red")], ""), 15) = “★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★“
link()
Status: new
The new link() function will take a URL string and output a clickable link.
Example: "For more tips and tricks, visit me on the web at " + link("Notion Things", "https://notionthings.com") = “For more tips and tricks, visit me on the web at Notion Things“
Function chaining with dot notation
Status: new
To make writing formulas more efficient and legible, we can use dot notation. Dot notation is a way of chaining together multiple functions for an object using a dot connector.
Example: now().formatDate("MMM ").upper().style("b", "blue") = SEPTEMBER
Some other powerful additions:
filter()
Returns the values in the list for which the condition is true.
Example: filter([1, 2, 3], current > 1) = [2, 3]
at()
Returns the value at the specified index in a list.
Example: at([1, 2, 3], 1) = 2
every()
Returns true if every item in the list satisfies the given condition; otherwise returns false.
Example: every([1, 2, 3], current > 0) = true
some()
Returns true if any item in the list satisfies the given condition; otherwise returns false.
Example: some([1, 2, 3], current == 2) = true
split()
Returns the list of values created by splitting input by separator.
Example: split("apple,pear,orange", ",") = [“apple”, “pear”, “orange”]
let()
Assigns a value to a variable and evaluates the expression using that variable.
Example: let(person, "Grace", "Hello " + person + "!") = “Hello Grace!”
flat()
Flattens a list of lists into a single list.
Example: flat([[1, 2], [3, 4]]) = [1, 2, 3, 4]
match()
Returns all matches of the regular expression as a list.
Example: match("Notion Notion", "Not") = [“Not”, “Not”]
I’ve called out these changes and additions to the Notion formula language as notable, but there is so much more that Formulas 2.0 offers! I’ve put together a handy reference guide that includes descriptions and examples of all of the functions, operators, constants, properties, and built-ins that are part of Formulas 2.0. You can filter these to see which items are new, which have changed, and which have been deprecated. Duplicate this reference guide and keep it handy as you begin the adventure into making Formulas 2.0 work for you!
NOTION FORMULAS 2.0 REFERENCE GUIDEAlso be sure to check out Notion’s official documentation on Formulas:
Formulas 2.0: How to use Notion’s new and improved formulas with your existing setups
Formula syntax & functions
An intro to formulas terminology
A beginner guide on how to write formulas
