Documentation

Grid Rating Question

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 labels config

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 optimizedStar style with imagesSlider style
Grid Rating Question Figure 01Grid Rating Question Figure 02Grid Rating Question Figure 03

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.

Code
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

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.
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-Used in reporting structure
imageMediaItemno-Top-level image shown above the question
number_of_pointsintno5 or label countNumber of rating points; slider and button styles support 2-10 points, star style 2-5
first_pointintno1 or first labelFirst point on the scale
labelsMapping[int, str | MediaItem]no-Custom labels for scale points
stylestringnosliderOne of "slider", "button", or "star"
randomizeboolnoFalseWhether to randomize row order
recodesDict[str, str]no-Optional recoding of rating values
dont_know_optionstrno""Optional "Don't know" option; reported with this text and stored as a sentinel value
skip_emptyboolnoFalseSkip question if no rows provided
defaultDict[str, int] | List[Dict[str, int]]norandomTest-data defaults keyed by row, or a list of candidate dictionaries — each simulated respondent picks one at random
custom_validatorCallable[[dict[str, int | str]], str | None]nostraight-line checkCalled 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_fieldstrno-Metadata field used for row and scale images.
show_image_labelboolnoTrueShow or hide labels for row and scale images.
image_sizeTuple[int, int]no(600, 600)Bounds for row and scale images.
number_secondsintno0Seconds to wait before allowing the respondent to continue
tagss.tag()no-For reporting and text substitution
idstrno-Optional stable identifier for this question

Example Code

Basic usage:

Code
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:

Code
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:

Code
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 DictResponse of the collected ratings
  • style="slider" shows an interactive scale; use button for tap options or star for visual flair
  • labels can help orient respondents, especially on non-obvious scales
  • A straight-line check is applied by default — pass your own custom_validator to replace it