Calculations and formulas

Use calculation fields to compute a number from a respondent’s answers. Add one when you need a computed value, such as a price or score, to use in your form.

Formula syntax

Formulas support decimal numbers, field references, parentheses, unary minus, and these arithmetic operators:

Syntax	Behavior
`+`, `-`	Addition and subtraction
`*`, `/`	Multiplication and division; these bind more tightly than `+` and `-`
`(...)`	Grouping

The ^ and % operators are not supported.

Reference a field with {{name}}. To use the score from a scoreable choice field, use {{name.score}}. score is the only supported accessor, and it works only on scoreable choice fields: multiple_choice, multi_select, checkboxes, and single_select. The scoring property supplies one number per option. For multi-answer fields, the score is the sum for unique selections.

A missing, empty, non-numeric, or array value counts as 0 in arithmetic. Calculations can also reference hidden fields declared in form settings.

IF function

Use IF(condition, then, else) to choose between two numeric expressions. It requires exactly three arguments, and only the selected branch is evaluated. You can nest IF expressions to a depth of 50.

Conditions support =, == (the same as =), !=, >, <, >=, <=, IN, and NOT IN. Use single or double quotes for string literals. IN and NOT IN are case-insensitive words for multi-value fields.

LOWER(x) and TRIM(x) are available only inside an IF condition, for loose text comparison. Other functions are not supported.

IF({{plan}} = 'Pro', {{seats}} * 12, {{seats}} * 20)

Calculation field options

Add a calculation element to a question page. The respondent does not answer it.

Property	Type	Default or limit
`formula`	string	Required; at least one character
`decimalPlaces`	integer	Default `2`; clamped to `0`–`20`
`prefix`	string	Up to 32 characters
`suffix`	string	Up to 32 characters

Publish checks formula syntax, field references, accessors, and cycles. A formula cycle is rejected.

Results and display

Calculation values are rounded to 10 decimal places. Division by zero produces a null result with the division_by_zero error. A non-finite result produces null with the invalid_number error.

The displayed value uses prefix, the value with decimalPlaces digits, and suffix. When piped into text, the value uses the field’s explicit decimalPlaces; otherwise it shows at most two decimals with trailing zeros dropped. Piping does not apply the prefix or suffix.

Calculation fields are not shown to respondents, and required has no use on them.

The server recomputes calculations on the start and question pages before routing, payment, and storage. It does not trust a calculation value sent by the client.

Examples

This form calculates an annual cost from a plan and seat count. It uses 12 per seat for Pro and 20 per seat for other plans.

{
  "mode": "page",
  "pages": [
    {
      "type": "form",
      "id": "p1",
      "ui": [
        {
          "type": "multiple_choice",
          "name": "plan",
          "label": "Choose a plan",
          "options": ["Basic", "Pro"]
        },
        {
          "type": "number_input",
          "name": "seats",
          "label": "Number of seats",
          "min": 1,
          "defaultValue": "1"
        },
        {
          "type": "calculation",
          "name": "annual_cost",
          "label": "Annual cost",
          "formula": "IF({{plan}} = 'Pro', {{seats}} * 12, {{seats}} * 20)",
          "decimalPlaces": 2,
          "prefix": "$"
        }
      ]
    }
  ],
  "end": [
    {
      "id": "e0",
      "type": "end",
      "ui": []
    }
  ]
}

This form uses the score from a scoreable choice field and adds it to a numeric base value.

{
  "mode": "page",
  "pages": [
    {
      "type": "form",
      "id": "p1",
      "ui": [
        {
          "type": "multiple_choice",
          "name": "features",
          "label": "Which feature matters most?",
          "options": ["Speed", "Reliability", "Support"],
          "scoring": [3, 2, 1]
        },
        {
          "type": "number_input",
          "name": "base",
          "label": "Base points",
          "min": 0,
          "defaultValue": "10"
        },
        {
          "type": "calculation",
          "name": "total_score",
          "label": "Total score",
          "formula": "{{features.score}} + {{base}}",
          "decimalPlaces": 0,
          "suffix": " points"
        }
      ]
    }
  ],
  "end": [
    {
      "id": "e0",
      "type": "end",
      "ui": []
    }
  ]
}