Scripting functions for lists

Returns a single list item's label to the page if it exists in the list. Can be used for testing, or to display items to a respondent. If the specified position does not exist in the list, undefined is returned at the script location.

Function: getListItemLabel(listName: string, position: number): string

Example: {{getListItemLabel("Q1List", 1)}}

Result: The label of the item at position 1 in Q1List.

Returns a single list item's source number to the page if it exists in the list. Can be used for testing, or to display items to a respondent. If the specified position does not exist in the list, undefined is returned at the script location.

Function: getListItemNumber(listName: string, position: number): number

Example: {{getListItemNumber("MyDynamicList", 1)}}

Result: The source list item number of the item currently in position 1 of MyDynamicList. For example, if position 1 in MyDynamicList is item 4 in the source list, this function returns 4.

Returns the item text of all items in the specified list as a JavaScript array, useful for scripting and custom logic.

Function: getListItemLabelsArray(listName: string): string[]

Example: {{getListItemLabelsArray("Q1List")}}

Return: The item text of all the items in the specified list, separated by commas.

Returns the item values of all items in the specified list as a JavaScript array, useful for scripting and custom logic.

Function: getListItemNumbersArray(listName: string): string[]

Example: {{getListItemNumbersArray("Q1List")}}

Return: The item values of all the items in the specified list, separated by commas.

Returns the item text of all items in the specified list as a formatted string, useful for displaying text directly to a respondent (e.g. in a question or message). Items are separated by commas and spaces.

Function: printListItemLabelsArray(listName: string): string

Example: {{printListItemLabelsArray("Q1List")}}

Return: The item text of all the items in the specified list, separated by commas and spaces.

Returns the item values of all items in the specified list as a formatted string, useful for displaying text directly to a respondent (e.g. in a question or message). Items are separated by commas and spaces.

Function: printListItemNumbersArray(listName: string): string

Example: {{printListItemNumbersArray("Q1List")}}

Return: The item values of all the items in the specified list, separated by commas and spaces.

Adds items to the dynamic list from another list. Items are always added to the end of the list.

Function: add(listName: string): void

Example: add("My source list");

Result: All items from “My source list” are added to the end of the dynamic list.

Function: add(listName: string, itemNumber: number): void

Example: add("My source list", 2);

Result: Item number 2 from “My source list” is added to the dynamic list.

Function: add(listName: string, startItemNumber: number, endItemNumber: number): void

Example: add("My source list", 4, 6);

Result: Items 4, 5, and 6 from “My source list” are added to the end of the dynamic list.

Adds items to a specific position in the dynamic list. If the item already exists in the list, it is moved to the specified position. If the insert position is greater than the number of items in the list, items are added to the end.t

Function: addAtPosition(listName: string, insertPosition: number): void

Example: addAtPosition("My source list", 3);

Result: All items in “My source list” are added to the dynamic list beginning at position 3.

Function: addAtPosition(listName: string, itemNumber: number, insertPosition: number): void

Example: addAtPosition("My source list", 2, 3);

Result: Item 2 from “My source list” is added at position 3 in the dynamic list.

Function: addAtPosition(listName: string, startItemNumber: number, endItemNumber: number, insertPosition: number): void

Example: addAtPosition("My source list", 4, 6, 3);

Result: Items 4, 5, and 6 from “My source list” are added to the dynamic list beginning at position 3.

Pulls items selected or not selected by a respondent in a question into the dynamic list. The specified question must use the dynamic list's source list or another dynamic list that shares the same source.

Function: carryForward(questionName: string): void

Example: carryForward("Familiar brands");

Result: Items selected in “Familiar brands” are added to the bottom of the dynamic list.  

Function: carryForward(questionName: string, isSelected: boolean): void

Example: carryForward("Familiar brands", false);

Result: Items not selected in “Familiar brands” are added to the bottom of the dynamic list.

Adds items to the dynamic list from a question where the values of those items meet a comparison criterion. Only works for ranking and constant sum question types.

Function: carryForwardCompareValues(questionName: string, comparisonOperator: string, value: number): void

Example: carryForwardCompareValues("Ranking question", "<=". 3);

Result: All items from “Ranking question” with a value less than or equal to 3 are added — in other words, the top three ranked items. Valid operators: <, <=, >, >=, =, != (not equal to).

Function: carryForwardCompareValues(questionName: string, compareFn: (value: number) => boolean): void

Example: carryForwardCompareValues("Ranking question", x => x >=3 && x <=6);

Result: Applies the comparison function to each item's value. Items where the function returns true are added to the dynamic list. In this example, items with values between 3 and 6 (inclusive) are added. Learn about arrow function syntax.

Adds items to the dynamic list from the row list of a grid question when column selections for that row match a condition. Only works for single-select and multi-select grids. The grid row list must be the source list of the dynamic list or share the same source.

Function: carryForwardGridRows(gridQuestionName: string, isSelected: boolean, columnNumber: number): void

Example: carryForwardGridRows("My grid question", true, 3);

Result: All row items in “My grid question” where column 3 is selected are added to the dynamic list.

Function: carryForwardGridRows(gridQuestionName: string, isSelected: boolean, columnNumberArray: number[]): void

Example: carryForwardGridRows("My grid question", false, [1,3,5]);

Result: All row items in “My grid question” where columns 1, 3, and 5 are not selected are added to the dynamic list.

Randomizes the items currently in the dynamic list.

Function: randomize()

Example: randomize();

Result: All items previously added to the dynamic list appear in random order.

Function: randomize(startPosition: number, endPosition: number): void

Example: randomize(2, 4);

Result: Items at positions 2, 3, and 4 are randomized within those positions.

Removes items from the dynamic list.

Function: remove(listName: string): void

Example: remove("Dynamic list with shared source list");

Result: All items in the specified list are removed from the dynamic list.

Function: remove(listName: string, itemNumber: number): void

Example: remove("Source list", 4);

Result: Item 4 from “Source list” is removed from the dynamic list.

Function: remove(listName: string, startItemNumber: number, endItemNumber: number): void

Example: remove("Source list", 2, 5);

Result: Items 2, 3, 4, and 5 from “Source list” are removed from the dynamic list.

Sets a maximum length for the dynamic list. Items beyond the limit are removed. If the list has fewer items than the specified number, nothing happens.

Function: listMax(listLength: number): void

Example: listMax(4);

Result: The first four items are kept and the rest are removed.

Sets a minimum length for the dynamic list. Items from the source list are added at random until the minimum is reached. If the list already meets or exceeds the minimum, nothing happens.

Function: listMin(listLength: number): void

Example: listMin(7);

Result: Random items from the source list are added to the bottom of the dynamic list until there are 7 items.

Sets the exact length of the dynamic list. Items are added at random from the source list if the list is too short, or removed from the end if it is too long.

Function: setListLength(listLength: number): void

Example: setListLength(4);

Result: The dynamic list will contain exactly 4 items.

Reverses the order of all items in the dynamic list.

Function: reverse(): void

Example: reverse();

Result: Items appear in the opposite order. For example, items in positions 1, 2, 3, 4, 5 will appear as 5, 4, 3, 2, 1.

If statements let you conditionally add items based on a respondent's answers. For example, to show different list items based on a respondent's answer to a gender question:

• Males (value 1): items 1–4
• Females (value 2): items 5–8
• Both: items 9 and 10
• Chose not to specify (value 3): question is skipped

The script first saves the Gender value to a variable. The if statement checks whether it equals 1 — if so, items 1–4 are added. The else if checks for a value of 2 and adds items 5–8 if true. The final if statement adds items 9 and 10 for anyone who didn't choose value 3.

Results by gender value:

• Value 1: items 1, 2, 3, 4, 9, 10
• Value 2: items 5, 6, 7, 8, 9, 10
• Value 3: empty list — question is skipped

For more on JavaScript if statements, see this tutorial.