When and Why to Use
Use this when you need a numeric input within a defined range. It's best for:
Age, year, count, or frequency questions
Questions that require range-based recoding (e.g. age bands)
Validating attention checks with specific values
Supports optional recoding and validation logic.
Portrait Experience
Respondent is shown a numeric input with increment/decrement buttons.
Range boundaries are visible.
If input is outside the range or invalid, an error message appears inline.
Landscape Experience
Same as portrait, but with more space for contextual text or images.
Navigation and focus-friendly for remote/TV-based interactions.
Configuration Options
Option | Type | Required | Default | Description |
|
| yes | - | The prompt shown to the user |
|
| no | - | Optional image from |
|
| no |
| The valid numeric range for answers |
|
| no | random between range | Default test data for QA |
|
| no | - | Map ranges or percentages to buckets |
| `Callable[[str], str | None]` | no | - |
|
| no | - | Used to fill tokens in text and for reporting groupings |
Example Code
Simple numeric:
s.numeric_question("What year were you born in?", min_max=(1900, 2024))With recodes:
s.numeric_question( "How old are you?", min_max=(18, 100), recodes={ "18-25": "18-25", "26-54": "26-54", "55-74": "55-74", "75-100": "75+" } )With percentage-based recodes:
s.numeric_question( "How many times have you visited our website?", min_max=(0, 100), recodes={ "0-30%": "Low", "31-70%": "Medium", "71-100%": "High" } )With custom validator:
s.numeric_question( "How old are you?", min_max=(0, 120), custom_validator=lambda x: "Are you sure that you're 150 years old?" if x > 150 else None )
Notes
Recodes can use exact ranges (e.g., "18-25") or percentage bands (e.g., "0-30%")
Useful for transforming numeric answers into reportable categories
custom_validatoroverrides default validation, useful for edge-case checks