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