Expression Syntax

In SurveyJS, an expression is a mathematical formula or logical statement used to specify conditional rules or calculate values. With expressions, you can control the flow of your survey, manage question visibility and read-only state, perform in-survey computations, and more. Expressions are evaluated (that is, calculated to produce a result) in real time while a respondent fills out a form. This dynamic evaluation ensures that expression results are always up-to-date.

SurveyJS Form Builder provides a graphical user interface for constructing logical expressions—a pop-up dialog with a list of questions and custom variables to select from and available operators. This dialog appears when you click a Magic wand button next to an expression setting in the Property Grid. For example, you can find such settings within the Conditions category of a page or question.

Although the visual expression builder covers most use cases, it operates within certain limitations that do not allow you to construct any imaginable expression. To unlock the full capabilities of expressions, you need to get acquainted with the syntax rules. This guide will introduce you to expression structure, supported operators, and built-in functions that you can use for calculations within your form.

Any expression consists of operands and operators. Operands are values upon which an operator performs an action. Alongside literals (values like 3, true, or "selected"), expressions can use question values, custom variables, and function results as operands.

To use a question value in an expression, specify the Question name property value in curly brackets: {my-question-name}. Upon expression evaluation, the question name will be replaced with a real value. For example, the image below shows two questions with names nps-score and promoter-features. The latter question is displayed only when the nps-score value is 9 or higher. To configure this behavior, you need to do the following:

1. Select the promoter-features question on the design surface or in the survey tree.
2. Open the Conditions category and find the Make the question visible if setting in it.
3. Specify this setting with the following expression: {nps-score} >= 9.

For questions with a specified Data > Join identifier setting, use its value instead of the Question name value.

Complex question types (Multiple Textboxes, Dynamic Panel, matrices) support advanced syntax for accessing the values of their inner elements (individual textboxes, panels, rows, columns).

The advanced syntax may be useful in many cases, one of which is data validation in a Dynamic Panel. For instance, if the Dynamic Panel contains Start Date and End Date questions, you might want to check that the start date doesn't exceed the end date. To set up this configuration, follow these steps:

1. Add a Dynamic Panel to the design surface.
2. Add two Single-Line Input questions to the Dynamic Panel.
3. Select the first question, locate the Input type drop-down menu under the General category, and select Date.
4. Repeat step 3 for the second question.
   
   
5. Select the first question and enter start-date as the Question name setting value.
6. Select the second question and enter end-date as a value for the same setting.
   
   
7. Select the end-date question, locate the Validation rules setting under the Validation category, and click Add new rule.
   
   
8. Specify the following Error message: End date should be greater than start date.
9. Enter the following Validation expression: {panel.start-date} < {panel.end-date}.

To check that the validation rule works as expected, open the Preview tab, add a new entry to the Dynamic Panel, and select invalid start and end dates.

Custom variables are user-defined variables used to store dynamically calculated values. To use a custom variable in an expression, wrap its name in curly brackets, just like you do with question names: {my-custom-variable}. For information on how to define custom variables, refer to the following help topic:

How to Use Custom Variables in Form Calculations

Calculation functions produce results that can be used as operands in expressions. For example, the dateDiff() function computes a difference between two dates. The function's result can be used in a validation expression to ensure that the difference doesn't exceed a specified limit. Follow the instructions below to configure this behavior:

1. Add two Single-Line Input questions to the design surface.
2. Set their Input type to Date and Question name to start-date and end-date (perform steps 3 to 6 from the instructions for the Dynamic Panel).
3. Select the end-date question, locate the Validation rules setting under the Validation category, and click Add new rule.
   
   
4. Specify the following Error message: Difference between start and end dates must not be greater than 14 days.
5. Enter the following Validation expression: dateDiff({start-date}, {end-date}, "days") <= 14.
   
   

To verify the validation, open the Preview tab and select two dates that are more than 14 days apart.

Other calculation functions are used in expressions in a similar way. For more details, refer to the Calculation Functions section of this document.

Operators are symbols or keywords that define operations performed on operands. SurveyJS supports comparison, logical, and arithmetic operators.

Comparison operators are used to compare two values (or in case of empty and notempty, one value with undefined and null) and define whether the comparison is true or false. These operators are essential for managing the survey flow and implementing logic within your survey. The following table lists available comparison operators:

Logical operators combine or revert logical conditions to create complex logic for features like visibility, data validation, dynamic read-only state, etc. Available logical operators are described below:

Arithmetic operators perform simple mathematical calculations on numeric values. You can find the available arithmetic operators in the following table:

Calculation functions allow you to perform computations within your survey. All functions are divided into three groups: logical, date, and aggregation functions.

Expressions support one logical function—iif. It returns one value or the other based on whether a specified condition is true or false.
Example: "iif({question1} > 20, 'High', 'Low')"

For date calculations, you can use the following functions:

How to Calculate Duration Between Dates and Prefill a Form Field with the Duration Value

Aggregation functions are used to summarize, combine, or otherwise process a set of values into a single value.

Most survey questions support basic aggregation functions, such as sum, min, max, and avg. For Multi-Select Matrix, Dynamic Matrix, and Dynamic Panel, you can use advanced functions that aggregate values in a specific matrix column or panel question. The advanced functions provide an optional third parameter that allows you to filter values included in the calculation.

The following table describes all aggregation functions that you can use in expressions:

Examples for ...InArray functions:

• "sumInArray({matrixdynamic}, 'total', {categoryId} = 1)"
  Sums up values from a "total" matrix column but includes only the rows where a "categoryId" column equals 1.

• "minInArray({matrixdynamic}, 'quantity', {quantity} > 0 and {categoryId} = 1)"
  Finds a minimum value within a "quantity" matrix column but searches for it only in the rows where a "categoryId" column equals 1 and the values are positive.

• "maxInArray({matrixdynamic}, 'quantity', {quantity} < 100)"
  Finds a maximum value within a "quantity" matrix column, but the value should be under 100.

• "avgInArray({matrixdynamic}, 'quantity', {quantity} > 0)"
  Finds an average of values within a "quantity" matrix column, excluding zeroes.

• "countInArray({matrixdynamic}, 'quantity', {quantity} > 0 and {categoryId} = 1)"
  Finds the total number of matrix rows with a "quantity" column value greater than zero but includes only the rows where a "categoryId" column equals 1.