Skip to main content

Calculation syntax & examples

Learn how to refer to fields, linked records, today's date, and the record ID in a calculation, which results are allowed, and see examples for numbers, text, and dates.

Written by Leo

A calculation is a short piece of JavaScript. You write it in the editor of a Calculation field and refer to other fields by name. This article shows how to refer to values and what a calculation can return. It's meant to help you write your first formulas with confidence. Learn more about the calculation field →

The Calculation editor of the field Net operating income with the list of values that opens after typing @, such as Property_name, Property_ID, and Primary_contact

Note:

  • The last expression is the result. Don't start with return at the top level. Write the expression itself.

  • A calculation returns a number, text, or a date. Other results, such as true or false, a list, or an empty value, leave the field empty.

  • Check the preview. Use Preview with to test a calculation on a real record before you save it. Learn more about the preview →

Who can use calculations?

  • Calculation fields are available on all plans: Free, Plus, and Premium. See what each plan includes on our pricing page.

  • To add or change a field, you need Full access to the database app and a desktop or tablet.

Refer to values

In the calculation editor, type @ or start typing a field name to open the list of values you can use. Select one to insert it.

  • A value appears with a name that has no spaces. Tape replaces spaces and special characters in field names with an underscore and keeps upper and lower case. Only the letters A to Z, digits, _ and $ stay. For example, Unit price appears as Unit_price, and Hourly Rate as Hourly_Rate.

  • @ only opens the list. It isn't part of the calculation, so references you type by hand with @, such as @Sum of Amount or @Unit price, don't work. Use the name without @, such as Unit_price.

  • When you rename a field, the calculations that use it follow the new name.

Clicking the end of a calculation in the Calculation editor, typing + @Purch, and selecting Purchase_price in the list, which inserts Purchase_price into the calculation

You can insert:

  • Fields of this record, such as Price.

  • Record_ID: the ID of the record.

  • Today: today's date.

  • Fields of linked records. These are listed under the name of the relation field, for example Line_items.

Values of a field arrive in the calculation like this:

  • Number fields give a number.

  • Single line text fields give text. Multi line text fields give text with its HTML formatting.

  • Unique ID fields give the number as text.

  • Date, Created on, and Last edited on fields give a JavaScript date. For a date field with an end date, add .start or .end, for example Sprint.start and Sprint.end.

  • Single select and Status fields give the name of the option.

  • Multi select fields give a list of option names.

  • Member and Last edited by fields give a name. A member field with several people gives a list of names. Created by isn't available in calculations.

  • Email and Phone fields give a list of entries with a type and a value.

  • Task list fields give a list of tasks with a title, a description, and a due date. The list is empty when there are no tasks.

  • An empty field gives an empty value. Check for it with || or ??.

Fields of linked records

Write the relation field name, then the field of the linked records, then what you want from them:

  • Line_items.Amount.sum: the sum of the amounts.

  • Line_items.Amount.avg: the average.

  • Line_items.Amount.min and Line_items.Amount.max: the smallest and the largest value.

  • Line_items.Amount.all: a list of all values. Empty values are skipped.

  • Line_items.Amount.allWithNull: the same list with empty values kept.

Sum and average work for number fields. Minimum and maximum work for number and date fields.

A reference from another database app that links to this record is listed under the name of that database. Learn more about references →

Examples

A calculation doesn't need a field. Tape also works out fixed values, such as 1 + 1.

Total price:

Unit_price * Quantity

Price with 19% tax, rounded to two decimals:

Math.round(Unit_price * 1.19 * 100) / 100

A name from two fields:

First_name + ' ' + Last_name

Total of all line items of an invoice:

Line_items.Amount.sum

Average of related values, with a guard for records without links:

Line_items.Amount.all.length ? Line_items.Amount.avg : 0

Days until a deadline:

moment(Due_date).diff(Today, 'days')

Set Format to Number for number results and to Date for dates. Use None for text.

What you can use

A calculation supports standard JavaScript, including Math, Date, and Intl. Tape collects the values of the fields you use and runs the calculation on the server, in Node.js 18. You can use JavaScript up to ES2021.

  • Your JavaScript never runs in the browser or in the mobile app. It runs in an isolated environment on the server, and the apps only show the result.

  • A calculation has a time limit. Most calculations need only a few milliseconds.

  • A calculation can't wait. async, promises, setTimeout, and setInterval don't work, and a calculation can't load data from the web.

These libraries are available without importing them. Call each one by its name:

  • lodash or _ (Lodash 4.17.21): functions for lists, objects, and text.

  • moment (Moment.js 2.30.1): read, check, change, and format dates and times.

  • date_fns (date-fns 2.30.0): functions for dates.

  • date_fns_tz (date-fns-tz 2.0.1): time zones for date-fns, based on the Intl API.

  • uuid (uuid 8.3.2): create unique IDs in the RFC 4122 format.

  • cheerio (cheerio 1.0.0-rc.10): read values from HTML, with functions like in jQuery.

  • striptags (striptags 3.2.0): remove HTML tags from text.

  • minimatch (minimatch 9.0.5): compare text with a pattern, such as *.pdf.

  • jsonata (jsonata 1.8.6): query and transform JSON data.

Need another library? Submit a feature request in the Tape community → and tell us what it's for.

A date field is a JavaScript date. To show it in text, format it first. For example, this writes a due date as text, such as March 4, 2026:

date_fns.format(Due_date, 'MMMM d, yyyy')

Without formatting, the text shows the full date, such as Wed Mar 04 2026 00:00:00 GMT+0000.

Format a text result with Markdown

When Format is None, a text result can use Markdown. Tape shows it formatted on the web and in the mobile app. Tape supports GitHub Flavored Markdown, for example **bold**, lists that start with -, and links such as [Acme](https://acme.com). Each line break in the result starts a new line in the record.

  • A web address becomes a link. A valid address on its own, such as https://acme.com, is clickable.

  • A Markdown link opens in the same tab. To open a link in a new tab, use HTML with target="_blank", as shown below.

To put field values and line breaks into text, use a template literal. Wrap the text in backticks (`) and write each value as ${Field_name}. The text can run over several lines.

For example, this shows a short summary of a deal:

`**${Deal_name}**

- Budget: ${Budget}
- Stage: ${Stage}`

Format a text result with HTML

When Format is None, a text result can contain HTML, for example <b>, links, colors with style, or a small table. The record shows it formatted, on the web and in the mobile app. For safety, Tape removes scripts, event handlers such as onclick, forms, and links or images that don't use a safe web address (https://).

For example, this shows the status in bold:

'<b>' + Status + '</b>'

Format a number before you put it into text. For example, this shows an amount with two decimals, and 0.00 when the field is empty:

`<p>Total: <b>${(Amount ?? 0).toFixed(2)} €</b></p>`

Besides style on a single element, you can add a <style> block with CSS selectors. It styles all matching elements in the result, for example <style> button { margin: 4px; } </style> for space between buttons.

The Edit calculation window in full screen with a formula that returns HTML, and the preview with Riverstone Eight showing Due diligence in bold and Inspection report missing in orange

To use Tape's colors, write these CSS variables in style, for example style="color: var(--tape-color-danger)":

  • --tape-color-primary: the blue of Tape (#1164A3). --tape-color-primary-dark-10 (#0F5A93) and --tape-color-primary-dark-20 (#0E5082) are 10% and 20% darker. --tape-color-primary-10 and --tape-color-primary-20 are the same blue at 10% and 20% opacity.

  • --tape-color-danger: red (#EB5757). --tape-color-danger-dark-10 (#D44E4E), --tape-color-danger-dark-20 (#BC4646), --tape-color-danger-10, and --tape-color-danger-20 work the same way as for the blue.

  • --tape-color-success: green (#007959).

  • --tape-color-lightest, --tape-color-lighter, --tape-color-mediumlight, --tape-color-light, --tape-color-dark, --tape-color-darker, and --tape-color-darkest: neutral shades for backgrounds, borders, and text. --tape-color-lightest is white (#FFFFFF), and --tape-color-darkest is the color of the text (#37352F). --tape-color-mediumlight is #EBEDEF, --tape-color-light is #EEEEED, and --tape-color-dark is #CED8DD. --tape-color-lighter and --tape-color-darker are the text color at 3% and 85% opacity.

Add buttons, collapsible sections, and links

A text result in HTML can also show these elements:

  • Buttons: <button>Open contract</button> shows a blue button. Add type="danger", type="outline", or type="outline-danger" for a red, an outlined, or an outlined red button. A button runs no code on its own, so onclick doesn't work. To open a web page, wrap the button in a link: <a href="https://acme.com" target="_blank"><button>Open contract</button></a>.

  • Collapsible sections: <details> with a <summary> shows a heading that opens and closes the content below it. Add open to <details> to show it open. Tape gives <summary> a default style, and your own styles apply on top.

  • Links: a link field gives a list of web addresses, so Website[0] is the first one. An empty link field gives an empty list, so check Website.length first. Add target="_blank" to a link to open it in a new tab.

For example, this shows the first address of a Website link field as a button:

Website.length ? `<a href="${Website[0]}" target="_blank"><button>Open website</button></a>` : ''

This shows the Title of a record as a heading that opens to its Note, in Tape's blue:

`<details>
<summary style="font-weight: 600;">${Title}</summary>
<p style="color: var(--tape-color-primary);">${Note}</p>
</details>`

The Edit calculation window in full screen with a formula that returns the first address of the Listing links field as the blue button Open listing, the buttons Reject offer (danger), Request documents (outline), and Cancel deal (outline-danger), and an open collapsible section, and the preview with Riverstone Eight showing the four buttons and Due diligence notes opened to Inspection report is missing in blue

Common problems

  • The field stays empty. The result may be a true or false value, a list, an empty value, or not a number. Make the calculation return a number, text, or a date.

  • Average of an empty list. A record without linked values gives no valid average. Check the length first, as in the example above.

  • Text that looks like a number. Some values arrive as text. Convert them with Number().

  • A line ends and the next one starts with a bracket or a backtick. Add a semicolon to end the first line.

Learn more: The calculation field cheat sheets in the Tape community have many examples to copy:

FAQs

Do I need to know JavaScript?

No, simple calculations such as adding, multiplying, and joining text need only a few operators. For more, a little JavaScript helps.

Can I round a number?

Yes. Use Math.round, Math.floor, or Math.ceil, as in the example above.

Can I use today's date?

Yes. Insert Today from the list after typing @.

Can I use the record ID?

Yes. Insert Record_ID from the list. To show the number that counts up in your database app, add a Unique ID field and use it in the calculation. Learn more about the unique ID field →

Are there other field types?

Yes! Database apps have fields for text, numbers, dates, members, files, relations, calculations, and more. See every field type in Intro to fields →

Still have more questions? Find answers and get help from community experts in the Tape community →.

Did this answer your question?