When and Why to Use
Use this to collect structured responses across multiple attributes. Ideal for:
- Marking multiple items on the same scale (e.g. product attributes)
- Capturing matrix-style input efficiently
- Comparing the same options across rows
Supports recoding, randomization, and media-based rows.
Other Names and Formats
A Grid Select Question is a single-select matrix, single-response matrix, multiple-choice grid, radio button grid, or matrix table. Each row accepts one answer from the shared column choices. With ordered agreement labels, it can present a Likert-style matrix; with categorical labels, it records categories instead.
Choice and Grid Groups
Pass dictionaries to rows, options or both to add non-selectable group headings to the grid rows or answer choices. The member strings remain the response keys and values. See Choice and Grid Groups for syntax, randomization and authoring rules.
Chat Style
- The full grid is presented in the Chat flow, with radio buttons or buttons for each row according to
style - Rows and labels adapt to the available space; preview long grids on mobile
- Specify option input appears below the corresponding row when selected
Traditional Style
- Grid is shown in tabular layout with rows as items and columns as options
- Works well with keyboard/remote input
- Hover/focus interaction highlights active cell
| Traditional with buttons | Traditional with Radio | Mobile optimized traditional |
|---|---|---|
![]() | ![]() | ![]() |
Explicit Don't know response
Set dont_know_option="Don't know" to offer a separate choice for each row. Respondents can switch between that choice and an ordinary answer; other rows retain their own answers. The configured label stays distinct from the row's substantive choices, including when ordinary choices are stored as a sorted numeric scale. Explicit opt-outs are excluded from the built-in straight-line check.
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 single selected value. 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', 'radio'] | no | radio | "radio" or "button" display style |
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 that are never randomized |
specify_option | str | no | - | Adds an "Other" option to all rows |
specify_text | str | no | "Please specify" | Prompt for the specify input |
image | MediaItem | no | - | Image shown above the question |
recodes | Dict[str, str] | no | - | Maps options to alternate values |
custom_validator | Callable[[dict[str, str | int]], str | None] | no | straight-line check | Called with the complete parsed grid in both chat and traditional experiences; sorted choices use integers. Return an error message to reject the response, or None to accept. |
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. |
skip_empty | bool | no | False | Skip the question when there are no rows or no options |
default | Dict[str, str | List[str]] | List[Dict[str, str | List[str]]] | no | random | Per-row defaults for test data, or a list of candidate dictionaries — each simulated respondent picks one at random. Within one dictionary, a per-row list supplies candidates the respondent's pick is sampled from |
sorted | Literal['ascending', 'descending'] | no | None | Store each row's answer in reporting as a numeric scale derived from option order. Respondents still see a normal grid select. Cannot be combined with randomize_options. |
number_seconds | int | no | 0 | Seconds to wait before allowing the respondent to continue |
tags | s.tag() | no | - | Used for token substitution and grouping in reporting |
id | str | no | - | Optional stable identifier for this question |
Example Code
Basic usage:
s.grid_select_question( "Please rate the following aspects of the product", row_name="Product Aspect", rows=["Quality", "Price", "Service", "Delivery"], options=["Poor", "Fair", "Good", "Very Good", "Excellent"] )
With recodes:
s.grid_select_question( "Rate the following aspects of the experience", row_name="Attribute", rows=["Cleanliness", "Friendliness", "Wait Time"], options=["Poor", "Fair", "Good", "Excellent"], recodes={ "Poor": "1", "Fair": "2", "Good": "3", "Excellent": "4" } )
With custom validator:
s.grid_select_question( "Rate the following aspects of {brand} cars", row_name="Attribute", rows=["Design", "Comfort", "Technology"], options=["Poor", "Fair", "Good", "Excellent"], tags=s.tag(brand="Tesla"), custom_validator=lambda r: "Please vary your responses" if len(dict.fromkeys(r.values())) == 1 else None )
Stored as a numeric scale for reporting:
s.grid_select_question( "How much do you agree with each statement?", row_name="Statement", rows=["The setup was easy", "Support was helpful", "I would recommend it"], options=["Strongly disagree", "Disagree", "Neutral", "Agree", "Strongly agree"], sorted="ascending" )
Notes
- Set
style="button"for a more compact tap-friendly interface - Use
recodesto make scale responses easier to analyze - The built-in straight-line check evaluates substantive responses and excludes explicit opt-outs; pass your own
custom_validatorto override it specify_optionenables per-row free text for non-listed choices- Returns a
DictResponsekeyed by row, which behaves like a plain Python dict sortedis useful when the options form an ordered scale and you want reporting to treat each row's answer as a number. Withsorted="ascending"the first option is stored as1, the second as2, and so on;sorted="descending"reverses this, storing the first option as the highest value and the last as1. Respondents still pick from the option labels. Because the values come from the option order,sortedcannot be used withrandomize_options(row order can still be randomized withrandomize).



