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.

Chat Style

• Each row is presented individually with a rating interface (slider, star, or button)
• User can scroll vertically through rows
• Labels and anchors are shown depending on the labels config

Button style	Slider style	Star style with an image

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

Configuration Options

Option	Type	Required	Default	Description
question	string	yes	-	The prompt shown to the user
rows	`List[str	MediaItem]`	yes	-
row_name	string	yes	-	Used in reporting structure
image	MediaItem	no	-	Top-level image shown above the question
number_of_points	int	no	5	Number of rating points
first_point	int	no	1 or first label	First point on the scale
labels	Dict[int, str]	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" fallback
skip_empty	bool	no	False	Skip question if no rows provided
default	Dict[str, int]	no	random	Test data defaults per row
custom_validator	`Callable[[Dict[str, int]], str	None]`	no	-
image_label_field	str	no	-	Field used for row image labels
show_image_label	bool	no	True	Show/hide row image labels
image_size	Tuple[int, int]	no	-	Size to render row images
tags	s.tag()	no	-	For reporting and text substitution

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

• 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
• custom_validator can enforce variation or prevent straight-lining