Scripting functions for lists

Returns the label of a single list item at the specified position. If the position doesn't exist, undefined is returned.

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

Example 1: Why did you choose {{getListItemLabel("Q1List", 1)}}?

Return: Why did you choose Blue?

Example 2: Why did you choose {{getListItemLabel("Q1List", 5)}}?

Return: Why did you choose undefined?

Returns the item text of all items in the specified list as a JavaScript array.

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

Array: ["Blue","Green","Red","Yellow"]

Example 1: How do you feel about {{getListItemLabelsArray("Q1List")}}?

Return: How do you feel about Blue,Green,Red,Yellow?

Example 2: How do you feel about {{getListItemLabelsArray("Q1List")[0]}}?

Return: How do you feel about Blue?

Returns the source list item number at the specified position. If the position doesn't exist, undefined is returned.

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

Example 1: Why did you choose {{getListItemNumber("Q1List", 1)}}?

Return: Why did you choose 1?

Example 2: Why did you choose {{getListItemNumber("Q1List", 5)}}?

Return: Why did you choose undefined?

Returns the source list item numbers of all items in the specified list as a JavaScript array.

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

Array: ["1","2","3","4"]

Example 1: Why did you choose item {{getListItemNumbersArray("Q1List")}}?

Return: Why did you choose 1,2,3,4?

Example 2: Why did you choose item {{getListItemNumbersArray("Q1List")[0]}}?

Return: Why did you choose 1?

Returns the number of items in a list.

Function: getListLength(listName: string): number

Example: The number of possible items is {{listLength("Q1List")}}.

Return: The number of possible items is 4.

Returns true or false based on whether a source list item exists in a dynamic list.

Function: listHasSourceItem(listName: string, itemNumber: number): boolean

The examples below assume a dynamic list called ColorsChosen containing Blue (item 1) and Yellow (item 4). 

Example 1: The list contains the item Blue: {{listHasSourceItem("ColorsChosen", 1)}}

Return: The list contains the item Blue: true

Example 2: The list contains the item Green: {{listHasSourceItem("ColorsChosen", 2)}}

Return: The list contains the item Green: false

Example 3: {{listHasSourceItem("ColorsChosen", 4) ? "Why do you like Yellow?" : "Why did you not choose Yellow?"}}

Return: Why do you like Yellow?

Returns the label of a single list item at the specified position. If the position doesn't exist, the function returns blank.

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

Example 1: How do you feel about {{printListItemLabel("Q1List", 1)}}?

Return: How do you feel about Blue?

Example 2: How do you feel about {{printListItemLabel("Q1List", 5)}}?

Return: How do you feel about ?

Returns all item labels as a formatted, comma-delimited string intended for display to respondents. Does not behave like an array in custom code.

Function: printListItemLabelsArray(listName: string): string

Example 1: How do you feel about {{printListItemLabelsArray("Q1List")}}?

Return: How do you feel about Blue, Green, Red, Yellow?

Example 2: How do you feel about {{printListItemLabelsArray("Q1List")[3]}}?

Return: How do you feel about Blue, Green, Red, Yellow[3]?

Returns the source list item number at the specified position. If the position doesn't exist, the function returns blank. 

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

Example 1: Why did you choose brand {{printListItemNumber("Q1List", 1)}}? 

Return: Why did you choose brand 1?

Example 2: Why did you choose brand {{printListItemNumber("Q1List", 5)}}?

Return: Why did you choose brand ?

Returns all item numbers as a formatted, comma-delimited string intended for display to respondents. Does not behave like an array in custom code.

Function: printListItemNumbersArray(listName: string): string

Example 1: How do you feel about {{printListItemNumbersArray("Q1List")}}?

Return: How do you feel about 1, 2, 3, 4?

Example 2: How do you feel about {{printListItemNumbersArray("Q1List")[3]}}?

Return: How do you feel about ?

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");

Return: 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);

Return: 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);

Return: 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.

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

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

Return: 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);

Return: 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);

Return: 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");

Return: 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);

Return: 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);

Return: 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);

Return: 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);

Return: 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]);

Return: 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();

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

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

Example: randomize(2, 4);

Return: 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");

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

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

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

Return: 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);

Return: 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);

Return: 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);

Return: 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);

Return: The dynamic list will contain exactly 4 items.

Reverses the order of all items in the dynamic list.

Function: reverse(): void

Example: reverse();

Return: 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.