MaxDiff Question

When and Why to Use

Use this to identify the most and least preferred items from a set. It's ideal for:

Prioritizing features, messages, or concepts
Understanding tradeoffs in preferences
Reducing scale bias compared to traditional rating questions

Supports full MaxDiff logic with dynamic sets, randomization, and chat and traditional display styles.

Chat Experience

Respondents answer twice per set: once for each label (e.g. "Least" and "Most")

Traditional Experience

Each set is shown once with both labels side by side (e.g. "Select Least and Most")
Ideal for desktop or larger screen interactions

Chat experience

Traditional experience

Traditional experience on mobile

Configuration Options

Option	Type	Required	Default	Description
question	string	yes	-	Prompt shown above the MaxDiff sets
items	List[str] or List[List[str]]	yes	-	Flat list (auto-generated sets) or custom list of sets
labels	List[str]	yes	-	Two labels for the selection ends (e.g. ["Least", "Most"])
image	MediaItem	no	-	Optional image shown above the sets
randomize	bool	no	False	Randomize item order per set
custom_validator	`Callable[[Dict], str	None]`	no	-
dont_know_option	str	no	-	Optionally adds a "Don't know" choice
`tags`	s.tag()	no	-	Used for substitution and grouping in reporting

Example Code

Simple list with auto-generated sets:

car_brands = ["Ford", "Toyota", "Honda", "Tesla", "BMW", "Audi"] s.max_diff_question( "Which of the following car brands do you prefer?", items=car_brands, labels=["Least", "Most"] )

Chat version with label substitution:

s.max_diff_question( "Which of the following cars do you prefer the **{label}**?", items=["Ford", "Toyota", "Honda", "Tesla"], labels=["Least", "Most"] )

Custom sets and tag substitution:

for brand in ["Ford", "Toyota"]: s.max_diff_question( f"Which of the following {brand} cars do you prefer?", items=[["Focus", "Fiesta", "Mustang"], ["Fusion", "Explorer", "Escape"]], labels=["Least", "Most"], s.tag(brand=brand ))

Notes

If items is a flat list, sets are generated automatically
For chat layouts, always include {label} in your question text
Responses are returned as a dictionary per set with selected values for each label
Use custom_validator for logic like ensuring diversity across sets or detecting straight-lining