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 Images | Traditional - Mobile optimized |
|---|---|
![]() | ![]() |
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
| Option | Type | Required | Default | Description |
|---|---|---|---|---|
specify_row | str | None | no | None | Row in rows that lets the respondent supply a label. |
specify_row_text | str | no | "Please specify" | Non-blank prompt for the row label. |
dont_know_option | str | no | '' | Optional explicit opt-out label; per row for grids, otherwise for the whole question |
| question | string | yes | - | The prompt shown to the user |
| rows | List[str | MediaItem] | Dict[str, List[str | MediaItem]] | yes | - | Rows as a flat list or groups under display headings |
| row_name | string | yes | - | Label used in reporting and data schema |
| options | List[str | MediaItem] | Dict[str, List[str | MediaItem]] | yes | - | Options as a flat list or groups under display headings |
| style | Literal['button', 'checkbox'] | no | checkbox | "checkbox" or "button" style inputs |
| randomize | bool | no | False | Randomize row order |
| randomize_options | bool | no | False | Randomize option order per row |
| other_options | List[str] | no | - | Additional options to present to the user |
| fixed_options | List[str] | no | - | Options not affected by randomization |
| exclusive_options | List[str] | no | - | Options that deselect others in same row |
| specify_option | str | no | - | Adds an "Other" input to each row |
| specify_text | str | no | "Please specify" | Prompt shown when specifying input |
| image | MediaItem | no | - | Top-level image shown above the question |
| recodes | Dict[str, str] | no | - | Map of option values to alternate codes |
| default | Dict[str, List[str]] | List[Dict[str, List[str]]] | no | random | Per-row default selections for test data, or a list of candidate dictionaries — each simulated respondent picks one at random |
| skip_empty | bool | no | False | Skip the question when there are no rows or no options |
| image_label_field | str | no | - | Metadata field used to label row and option images. |
| show_image_label | bool | no | True | Show or hide labels for row and option images. |
| image_size | Tuple[int, int] | no | 600x600 | Pixel bounds for row and option images. |
custom_validator | Callable[[dict[str, list[str]]], str | None] | no | straight-line check | Receives the complete parsed grid in both experiences; return an error message to reject, or None to accept |
| number_seconds | int | no | 0 | Seconds to wait before allowing the respondent to continue |
tags | s.tag() | no | - | Used in text substitution and reporting groupings |
| id | str | no | - | Optional stable identifier for this question |
Example 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:
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:
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 ass.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
DictResponsemapping each row to the list of selected options, which behaves like a plain Python dict


