Documentation

Multi Select Grid Question

When and Why to Use

Use this to let users select multiple items from each row of a grid. Best for:

  • Capturing multiple associations across brands or features
  • Structured multi-select input
  • Attribute-based tagging questions

Supports recoding, exclusive options, and visual media rows.

Other Names and Formats

A Multi Select Grid Question is a checkbox grid, multiple-response matrix, multiple-answer matrix, or multi-select matrix. Respondents select all applicable column choices for each row, making this format useful for brand and attribute associations.

Choice and Grid Groups

Pass dictionaries to rows, options or both to add non-selectable group headings to the grid rows or answer choices. Headings do not change the selection limit or the returned row and option values. See Choice and Grid Groups for syntax, randomization and authoring rules.

Chat Style

  • The complete grid appears in the Chat flow, with checkboxes or buttons for each row
  • Input is grouped per row with selectable option tiles
  • Specify inputs appear inline below their respective rows

Traditional Style

  • Grid layout with rows and columns visible at once
  • Checkbox-style inputs allow multiple selections per row
  • Optimized for keyboard and remote navigation
Traditional with ImagesTraditional - Mobile optimized
Multi Select Grid Question Figure 02Multi Select Grid Question Figure 03

Explicit Don't know response

Set dont_know_option="Don't know" for an exclusive choice in each row. Selecting it clears the other selections in that row; choosing an ordinary option clears the opt-out for that row. Answers in other rows remain independent. The complete parsed grid reaches your custom validator in both survey experiences.

Respondent-supplied row labels

Include a row such as "Other activity" in rows, then set specify_row="Other activity" and specify_row_text="Which other activity?". The respondent supplies a non-blank label and answers that row. Use the original row label to look up the answer in survey code. Reports keep the respondent's label beside that answer under specified_row. In a one-row-at-a-time flow, the label is collected before the row's answer.

This is independent of specify_option, which collects an unlisted answer choice within a row.

See Other row labels for setup, an example and reporting behavior.

Images in rows and options

Both rows and options can mix ordinary text and image attachments, including within groups. Use image_label_field to choose labels from attachment metadata. Set show_image_label=False to hide captions for images while keeping ordinary text labels visible. The same label on both axes can refer to different images.

Each row retains a list of selected values. The response uses the resolved labels. See Choice and Grid Groups for grouping rules.

Configuration Options

OptionTypeRequiredDefaultDescription
specify_rowstr | NonenoNoneRow in rows that lets the respondent supply a label.
specify_row_textstrno"Please specify"Non-blank prompt for the row label.
dont_know_optionstrno''Optional explicit opt-out label; per row for grids, otherwise for the whole question
questionstringyes-The prompt shown to the user
rowsList[str | MediaItem] | Dict[str, List[str | MediaItem]]yes-Rows as a flat list or groups under display headings
row_namestringyes-Label used in reporting and data schema
optionsList[str | MediaItem] | Dict[str, List[str | MediaItem]]yes-Options as a flat list or groups under display headings
styleLiteral['button', 'checkbox']nocheckbox"checkbox" or "button" style inputs
randomizeboolnoFalseRandomize row order
randomize_optionsboolnoFalseRandomize option order per row
other_optionsList[str]no-Additional options to present to the user
fixed_optionsList[str]no-Options not affected by randomization
exclusive_optionsList[str]no-Options that deselect others in same row
specify_optionstrno-Adds an "Other" input to each row
specify_textstrno"Please specify"Prompt shown when specifying input
imageMediaItemno-Top-level image shown above the question
recodesDict[str, str]no-Map of option values to alternate codes
defaultDict[str, List[str]] | List[Dict[str, List[str]]]norandomPer-row default selections for test data, or a list of candidate dictionaries — each simulated respondent picks one at random
skip_emptyboolnoFalseSkip the question when there are no rows or no options
image_label_fieldstrno-Metadata field used to label row and option images.
show_image_labelboolnoTrueShow or hide labels for row and option images.
image_sizeTuple[int, int]no600x600Pixel bounds for row and option images.
custom_validatorCallable[[dict[str, list[str]]], str | None]nostraight-line checkReceives the complete parsed grid in both experiences; return an error message to reject, or None to accept
number_secondsintno0Seconds to wait before allowing the respondent to continue
tagss.tag()no-Used in text substitution and reporting groupings
idstrno-Optional stable identifier for this question

Example Code

Code
s.grid_multi_select_question( "What do you associate with these brands? Select all that apply", row_name="Brand", rows=["Coke", "Pepsi", "Dasani", "Fanta"], options=["Tasty", "Refreshing", "Cool", "Value", "Convenient"] )

With recodes:

Code
s.grid_multi_select_question( "What do you associate with these brands?", row_name="Brand", rows=["Coke", "Pepsi", "Fanta"], options=["Tasty", "Cool", "Value"], recodes={ "Tasty": "Product", "Cool": "Brand", "Value": "Pricing" } )

With exclusive and specify:

Code
s.grid_multi_select_question( "Select all that apply to each option below", row_name="Item", rows=["Feature A", "Feature B"], options=["Useful", "Overused", "Unknown"], exclusive_options=["Unknown"], specify_option="Other" )

Notes

  • The method name is grid_multi_select_question; call it as s.grid_multi_select_question(...)
  • exclusive_options allow per-row mutual exclusivity
  • recodes simplify grouping similar concepts in analysis
  • By default, custom_validator performs a straight-line check that rejects responses with the same value in every cell; pass your own function to override it
  • Use randomize_options to avoid order bias
  • Returns a DictResponse mapping each row to the list of selected options, which behaves like a plain Python dict