Expressions

An expression is a piece of JavaScript that computes a value from your variables. It is what an expression variable holds, and what a Set Variable action in expression mode and the If field of a Conditional action evaluate. Also called: formulas.

What you can write

Where: Variables panel → Design tab → the Value column of a row switched to expression; Set Variable action → ƒ → Expression; Conditional action → If.

• One JavaScript expression, not statements: count > 3 ? 'many' : 'few', template literals, array and string methods and arrow functions all work. A trailing ; makes it a statement, and the expression fails. When you need statements, wrap them in a function and call it on the spot: (() => { let total = 0; for (const n of [price, shipping, tax]) { total += n; } return total; })().
• Keep expressions short and simple, even though a wrapped function lets them grow. The field is a single line, so a long expression is hard to read and to fix. Split longer logic across several expression variables, each computing one named step: subtotal, then total reading subtotal.
• Other variables are referenced by their bare name: price * quantity.
• The standard JavaScript built-ins are available — Math, JSON, Date, String, Array, RegExp and the rest, except Intl — plus Math.clamp and the Color functions. Expression functions lists both namespaces and explains color values.
• Expressions cannot access the page or the network: there is no window, document or fetch, there are no timers, and a promise never resolves.
• Every evaluation starts clean: nothing an expression assigns carries over to its next evaluation or to another expression.

Completion opens after the . in Color. or Math. and on Ctrl + Space (macOS: ⌃ Space, with Control rather than ⌘), never while you type a name. Inside the parentheses of a Color or Math function the signature appears by itself.

When expressions are evaluated

An expression variable re-evaluates automatically whenever a variable it depends on changes, whether the change comes from an edit in the panel, a collaborator or a Set Variable action in preview. There is nothing to refresh or trigger. Its result is stored in the document, so everyone who opens it sees the same result.

• The change carries through chains: the expressions that read the new result evaluate again too, and so on.
• An expression reacts only to the variables it actually read the last time it ran. In onSale ? salePrice : price with onSale false, changing salePrice does nothing until onSale turns true.
• A stored result of Date.now() or Math.random() is a snapshot: it does not change on reload, and collaborators see the same number. It updates when a variable the expression read changes, when the expression is edited, or when any variable is created, renamed or deleted, which re-evaluates every expression in the document.

In preview

Preview evaluates expression variables on its own, against the viewer's session values, and never changes the stored results. The expressions of Set Variable and Conditional actions are evaluated every time the action runs, so Math.random() there gives a new number on each run.

Errors

A failing expression keeps its last good value: everything bound to the variable stays as it is, and expressions that read it get that value instead of an error. The variable shows a warning triangle in the Result column of the Variables panel, and the Validation console lists the error under one of the labels below — click the entry to open the variable. Collaborators see the same error, and it clears on the next successful evaluation.

Label	Cause
Expression error	The expression threw, for example on a misspelled or deleted variable. Also: syntax error, out of memory, deep recursion.
Expression timed out	The evaluation ran longer than the time limit.
Circular dependency	The variable reads itself, directly or through other variables. Every variable on the loop is marked.
Invalid value	The result is NaN, Infinity, a function, a Date or another non-plain object, or larger than the result limit.
Type mismatch	The result is not of the variable's type, such as '12' for a Number variable. null and undefined match no type.

Two conversions happen before the type check: a String variable takes a number or boolean result as text and an array or object as its JSON text, and a Color variable takes a color string in any accepted format.

An expression that has never evaluated successfully has no last good value: the Result column shows —, and expressions that read it get null, so broken + 1 gives 1.

Naming and renaming

A name is made of the letters A–Z and a–z, digits, _ and $, and does not start with a digit: no spaces, dashes or accented letters. Names are case-sensitive and unique.

• Rejected: JavaScript reserved words (class, default, new, let, static, true, null, …), undefined, NaN, Infinity, globalThis, arguments, eval, any name starting with __, and Color.
• Not rejected: names of built-ins. A variable named Math hides the built-in from every expression: Math.round(x) fails, and completion lists nothing after Math.. The same goes for JSON, Date and the rest.

Renaming a variable rewrites every reference to it in the same step, in expression variables and in Set Variable and Conditional expressions. An expression that does not parse is left untouched.

A rename is rejected as a whole, with a message starting Cannot rewrite references: that names the variable or layer, when a reference cannot be rewritten safely: the new name is already a local name where the reference sits (an arrow-function parameter, for example), or the reference sits inside a with block or in code that calls eval. Change that expression, then rename again.

Limits

note

Each evaluation is limited to:

• Time: 100 ms, then Expression timed out. Loops and regular expressions stop on time; a single built-in call over very large data can overrun before it is stopped.
• Memory: 32 MB for a single allocation, and 64 MB for all expressions in a browser tab together, then Expression error.
• Call stack: recursion that runs too deep fails with Expression error.
• Result size: 262,144 characters (256 KB) of the result written as JSON, then Invalid value.

Related

• Variables — types, value and expression variables, runtime values and preview sessions.
• Expression functions — the Color and Math tables.
• Binding properties to inputs and variables — make a property follow an expression's result.
• Keyboard shortcuts — completion keys.