Loop and Merge

Loop and Merge is a feature that allows you to repeat a group of questions and combine the responses into one data object. The loop can either iterate over the same set of questions for each item or adjust dynamically based on user input. In this example, you can select one or multiple SurveyJS products, and the survey will then ask a series of repeating questions about each selected product.

A question loop can be created using one of the complex question types:

• Single-Select Matrix
• Multi-Select Matrix
• Dynamic Matrix
• Dynamic Panel

Single- and Multi-Select Matrices produce a predefined number of loops—one for each matrix row. In contrast, Dynamic Matrix and Dynamic Panel types allow users to add new entries during the survey, generating new loops on the fly.

This example demonstrates a question loop based on a Dynamic Matrix. The number of loops is determined by the number of choices selected in a Checkboxes question, which acts as the loop driver.

To generate a single data object or data array, the loop driving question (Checkboxes) must be linked to the looping question (Dynamic Matrix). To create this connection, assign the same value to the valueName property for both questions. This shared value determines the name of the resulting data object or array. In this demo, valueName is set to "surveyjs-products".

If the paired question types return different data formats, additional configuration is needed for merging. For example, a Dynamic Matrix returns an array of objects, while a Checkboxes question typically returns an array of strings. To enable merging, configure the Checkboxes question to return an array of objects by setting the valuePropertyName property. For instance, if the Checkboxes question lists products, set valuePropertyName to product. Each selected item will then be saved as an object with the product field containing the selected value.

Loop and Merge requires the survey structure to change and display only one input field per survey page. To enable this structure, set the questionsOnPageMode property to "inputPerPage" at the survey level.

Each step in a loop displays a title. In Multi-Select and Dynamic Matrices, you can customize the title using the singleInputTitleTemplate property. This property supports dynamic placeholders ({rowIndex}, {rowName}, and {rowTitle}) and text piping from matrix cells and other survey questions.

The Dynamic Matrix question type allows users to add new rows—effectively creating new loops. However, if the number of loops is already determined by the selections in a loop driving question (such as a Checkboxes question), this feature becomes redundant. Disable it by setting the allowAddRows property to false in the Dynamic Matrix configuration and set the initial number of rows to zero by assigning 0 to the rowCount property.

If you want to use a Dynamic Panel for the loop, refer to the following example for detailed instructions:

Breakable Loop