When and Why to Use

Use this to collect open-ended responses where you want to capture thoughts, opinions, or unaided recall. It's ideal for:

• Brand recall
• Reasons behind choices
• Open feedback

Includes built-in AI validation to ensure quality. Responses are scored 1-5, and if too weak, the respondent is prompted to clarify.

Set quality_threshold=1 to avoid any termination. Set a custom_validator to override AI scoring.

Chat Experience

• Single-line or multiline input, depending on the short flag.
• Inline validation appears after submission.
• Retry prompt if response doesn't meet the quality threshold.
• If number_of_responses > 1, user is asked to submit multiple responses one at a time.

Multiple responses and an image	Plain text

Traditional Experience

• Supports multi-response collection if number_of_responses > 1.
• Respondents can enter several distinct answers before continuing.
• Retry logic and termination still apply per entry.

Single response and an image	Multiple responses	Mobile Optimized

Configuration Options

Option	Type	Required	Default	Description
question	string	yes	-	The prompt shown to the user
image	MediaItem	no	-	Optional image from s.media
default	string or list	no	random string	Default value(s) for test data
short	boolean	no	False	Use a compact text field (for names, labels, etc)
recodes	dict[str, str]	no	-	Optional text recodes (not often used here)
validation_instructions	string	no	-	AI instructions for what makes a valid response
quality_threshold	int	no	3	Minimum score (1–5) to accept a response
termination_threshold	int	no	1	Below this score after retries, survey terminates
max_attempts	int	no	3	Number of chances to clarify a low-quality response
custom_validator	`Callable[[str], str	None]`	no	-
number_of_responses	int	no	1	Number of distinct answers to collect
min_responses	int	no	-	Minimum number of answers required
tags	s.tag()	no	-	Used to fill tokens in text and group questions in reports

Example Code

s.text_question("When you think about cars, which brands immediately come to mind?")

With validation and image:

s.text_question( "What do you like about {brand} cars?", brand="Ford", validation_instructions="Please provide a specific reason, not just 'they're good'", image=s.media.ford_logo )

With a custom validator:

s.text_question( "Name a car brand you would never consider buying", custom_validator=lambda x: "That doesn't sound like a brand name" if x.lower() not in known_brands else None )

Notes

• AI validation is optional but enabled by default.
• To disable termination, set quality_threshold=1 or handle validation errors manually.
• custom_validator overrides AI validation entirely if provided.