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 →
Note:
The last expression is the result. Don't start with
returnat 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 withto 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 accessto 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 priceappears asUnit_price, andHourly RateasHourly_Rate.@only opens the list. It isn't part of the calculation, so references you type by hand with@, such as@Sum of Amountor@Unit price, don't work. Use the name without@, such asUnit_price.When you rename a field, the calculations that use it follow the new name.
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 textfields give text.Multi line textfields give text with its HTML formatting.Unique IDfields give the number as text.Date,
Created on, andLast edited onfields give a JavaScript date. For a date field with an end date, add.startor.end, for exampleSprint.startandSprint.end.Single select and
Statusfields give the name of the option.Multi select fields give a list of option names.
MemberandLast edited byfields give a name. A member field with several people gives a list of names.Created byisn't available in calculations.EmailandPhonefields give a list of entries with a type and a value.Task listfields 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.minandLine_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, andsetIntervaldon'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:
lodashor_(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 theIntlAPI.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.
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-10and--tape-color-primary-20are 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-20work 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-lightestis white (#FFFFFF), and--tape-color-darkestis the color of the text (#37352F).--tape-color-mediumlightis#EBEDEF,--tape-color-lightis#EEEEED, and--tape-color-darkis#CED8DD.--tape-color-lighterand--tape-color-darkerare 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. Addtype="danger",type="outline", ortype="outline-danger"for a red, an outlined, or an outlined red button. A button runs no code on its own, soonclickdoesn'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. Addopento<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 checkWebsite.lengthfirst. Addtarget="_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>`
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?
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?
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?
Can I use today's date?
Yes. Insert Today from the list after typing @.
Can I use the record ID?
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?
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 →.
