When and Why to Use
Use this when the respondent can select more than one option. Ideal for:
• Attitudes, experiences, or features that apply in parallel
• “Select all that apply” questions
• Showing both fixed and exclusive choices (e.g. “None of the above”)
Supports image-based choices, randomization, “Other (specify)”, and recodes.
Portrait Experience
• Options shown as checkboxes or tap-to-select tiles.
• If max_options is set, selection becomes disabled once the limit is reached.
• Exclusive options deselect others when tapped.
• Specify input appears inline below the selected “Other” option.
Landscape Experience
• Same logic as portrait, but more layout flexibility.
• Wider layout for media items, and better keyboard/remote navigation support.
Configuration Options
Option | Type | Required | Default | Description |
question | string | yes | - | The prompt shown to the user |
options | `List[str | MediaItem]` | yes | - |
max_options | int | no | all | Limit how many items can be selected |
image | MediaItem | no | - | Image shown above the question |
randomize | bool | no | False | Shuffle options (except fixed ones) |
fixed_options | List[str] | no | - | Options that remain static during randomization |
exclusive_options | List[str] | no | - | Options that deselect all others when chosen |
disabled_options | List[str] | no | - | Options to grey out/disable |
specify_option | str | no | - | Adds an “Other” option requiring input |
specify_text | str | no | “Please specify” | Prompt shown with specify_option |
default | List[str] | no | random choices | Test data default selections |
recodes | Dict[str, str] | no | - | Maps response(s) to grouped value(s) |
custom_validator | `Callable[[List[str]], str | None]` | no | - |
skip_empty | bool | no | False | If True, skips question if no valid options |
image_label_field | str | no | - | Field used to label media options |
show_image_label | bool | no | True | Whether to show image captions |
image_size | Tuple[int, int] | no | - | Display size for images in options |
**topics | dict | no | - | Replaces tokens in text and supports grouped reporting |
Example Code
s.multi_select_question( "What did you enjoy about the experience?", options=["The food", "The service", "The atmosphere", "The price"], fixed_options=["Other"], exclusive_options=["Other"], specify_option="Other", recodes={ "The food": "food", "The service": "service", "The atmosphere": "atmosphere", "The price": "price", "Other": "other" } )With max options and validation:
s.multi_select_question( "Select up to two brands you most associate with luxury", options=["Lexus", "BMW", "Audi", "Mercedes"], max_options=2, custom_validator=lambda x: "You must choose at least one brand" if not x else None )
Notes
• exclusive_options override other selections and enforce mutual exclusivity
• Use max_options to encourage prioritization
• recodes let you bucket answers for analysis
• specify_option is helpful for capturing outliers or edge cases