Question Type: max_diff_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 portrait vs. landscape display styles.

Portrait Experience

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

Landscape 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

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
**topics	dict	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"] )

Portrait 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 topic 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"], topic=brand )

Notes

If items is a flat list, sets are generated automatically
For portrait 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

API Reference

Question Type: multi_select_question

Question Type: grid_multi_select_question

Question Type: grid_numeric_question

Question Type: this_or_that_question