Text Question

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.