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[[str], str] | None	no	-	Function that returns a custom error message
dont_know_option	str	no	-	Optionally adds a "Don't know" choice
image_label_field	str	no	-	Label field to use for media items in the options
show_image_label	bool	no	True	Whether to show image labels for media options
image_size	Tuple[int, int]	no	-	Bounding box size for media options
number_seconds	int	no	0	Seconds to wait before allowing the respondent to continue
tags	s.tag()	no	-	Used for substitution and grouping in reporting
id	str | None	no	None	Optional stable identifier for this question

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