When and Why to Use
Use this to capture numeric or labeled ratings across multiple items in a structured format. It's useful for:
- Performance, satisfaction, or quality ratings
- Comparing several attributes on a common scale
- Collecting fine-grained opinion data
Supports sliders, buttons, and star ratings with configurable point labels.
Other Names and Formats
A Grid Rating Question is a matrix rating scale, rating matrix, or rating-scale grid. Slider and star styles are also described as a slider list and star rating grid. With agreement labels, the grid can present a Likert matrix, Likert scale grid, or agreement matrix. Each row records a rating on the configured scale.
Grid Groups
Pass a dictionary to rows to divide related items with non-selectable group headings. Ratings and returned response keys continue to use the member row values. See Choice and Grid Groups for syntax, randomization and authoring rules.
Chat Style
- The complete grid appears in the Chat flow, with each row using its configured slider, star or button rating control
- User can scroll vertically through rows
- Labels and anchors are shown depending on the
labelsconfig
Traditional Experience
- Grid layout with rows as items and ratings as columns
- Ratings are input inline per row
- Star and slider styles are fully supported
| Button style, mobile optimized | Star style with images | Slider style |
|---|---|---|
![]() | ![]() | ![]() |
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.
See Other row labels for setup, an example and reporting behavior.
Images in rows and scale labels
Mix text and image attachments in rows or in the labels mapping. Set image_label_field to choose the metadata field used for stable labels. show_image_label=False hides image captions and keeps ordinary text labels visible.
s.grid_rating_question(
"How much do you like each design?",
rows=[s.get_image("Designs", file_name="new.png"), "Current design"],
row_name="design",
number_of_points=5,
labels={1: s.get_image("Scale icons", file_name="low.png"), 5: "Like very much"},
image_label_field="file_name",
)
Rows use their resolved labels as keys. Scale points, defaults and reporting values keep their numeric encoding. You can choose row and scale images independently.
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. |
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 | - | Used in reporting structure |
image | MediaItem | no | - | Top-level image shown above the question |
number_of_points | int | no | 5 or label count | Number of rating points; slider and button styles support 2-10 points, star style 2-5 |
first_point | int | no | 1 or first label | First point on the scale |
labels | Mapping[int, str | MediaItem] | no | - | Custom labels for scale points |
style | string | no | slider | One of "slider", "button", or "star" |
randomize | bool | no | False | Whether to randomize row order |
recodes | Dict[str, str] | no | - | Optional recoding of rating values |
dont_know_option | str | no | "" | Optional "Don't know" option; reported with this text and stored as a sentinel value |
skip_empty | bool | no | False | Skip question if no rows provided |
default | Dict[str, int] | List[Dict[str, int]] | no | random | Test-data defaults keyed by row, or a list of candidate dictionaries — each simulated respondent picks one at random |
custom_validator | Callable[[dict[str, int | str]], str | None] | no | straight-line check | Called with the complete parsed grid in both chat and traditional experiences; Don't know rows arrive as strings. Return an error message to reject the response, or None to accept. |
image_label_field | str | no | - | Metadata field used for row and scale images. |
show_image_label | bool | no | True | Show or hide labels for row and scale images. |
image_size | Tuple[int, int] | no | (600, 600) | Bounds for row and scale images. |
number_seconds | int | no | 0 | Seconds to wait before allowing the respondent to continue |
tags | s.tag() | no | - | For reporting and text substitution |
id | str | no | - | Optional stable identifier for this question |
Example Code
Basic usage:
s.grid_rating_question( "Please rate the following aspects of the product", rows=["Quality", "Price", "Service", "Delivery"], row_name="Product Aspect", number_of_points=5 )
With custom labels and recodes:
s.grid_rating_question( "How would you rate these aspects?", rows=["Speed", "Design"], row_name="Attribute", number_of_points=5, labels={ 1: "Very Poor", 3: "Neutral", 5: "Excellent" }, recodes={ "1": "Low", "2": "Low", "3": "Mid", "4": "High", "5": "High" } )
With star style and default values:
s.grid_rating_question( "Please rate your satisfaction with each brand", rows=["Brand A", "Brand B"], row_name="Brand", style="star", number_of_points=5, default={"Brand A": 4, "Brand B": 5} )
Notes
- Returns a
DictResponseof the collected ratings style="slider"shows an interactive scale; usebuttonfor tap options orstarfor visual flairlabelscan help orient respondents, especially on non-obvious scales- A straight-line check is applied by default — pass your own
custom_validatorto replace it



