Kid Picker Question

When and Why to Use

Use this when a study targets minors and you need a parent/guardian to:

confirm how many children fall within an age window,
record each child's age and gender (with optional recodes/labels),
select which child is currently available to continue.

Ideal for: youth studies, parental permission flows, household sampling where one child continues.

Chat Experience

Guided, multi-step prompts (count → ages → genders → availability).
Optional custom wording for each step (four question text fields).
Gender labels and "son/daughter" terms configurable via gender_map.

Traditional Experience

Sequential screens and compact multi-field forms.
Numeric inputs for counts/ages; single/multi-select for genders.
Final selector for the available child (or "None of the above").

Configuration Options

Option	Type	Required	Default	Description
`min_age`	`int`	no	`13`	Minimum eligible age.
`max_age`	`int`	no	`17`	Maximum eligible age.
`age_recodes`	`dict[int, str] \| None`	no	`None`	Map raw ages to recoded labels (e.g., 13→"13-15").
`gender_map`	`dict[str, str] \| None`	no	`{"Male": "son", "Female": "daughter"}`	Maps gender to child term for copy/substitution.
`question_1_text`	`str \| None`	no	`"How many children do you have between the ages of {min_age} and {max_age}?"`	Custom text for count prompt.
`question_2_text`	`str \| None`	no	`"For each child, please let us know their age"`	Custom text for ages prompt.
`question_3_text`	`str \| None`	no	`"Now, please let us know their gender"`	Custom text for genders prompt.
`question_4_text`	`str \| None`	no	`"Which, if any, of your children are available to take the survey now?"`	Custom text for availability prompt.
`id`	`str \| None`	no	`None`	Optional stable identifier prefix for the generated child picker questions.

Return Value

Optional[StringResponse] - The selected child. The response value is the child's raw age and gender, and the response carries age, gender, and name tags:

child.age - the recoded age when age_recodes is provided,
child.gender - the raw gender response,
child.name - the respondent-facing label (e.g., "16 year old son").

When a child is selected, the platform also stores reportable calculated fields named "Selected child age" and "Selected child gender". Returns None if the respondent reports no eligible children or selects the fixed "None" option at the availability question.

Example Code

Basic usage

from survey import Survey

s = Survey(**globals())

child_info = s.kid_picker_question(
    min_age=13,
    max_age=17,
)

if child_info:
    s.show_message(
        "Please ask your {child} to take the survey now.",
        tags=s.tag(child=child_info.name),
    )
else:
    s.terminate("Sorry, this survey is for children only.")

s.complete()

With age recodes and custom labels

child_info = s.kid_picker_question(
    min_age=5,
    max_age=18,
    age_recodes={5: "5-8", 6: "5-8", 7: "5-8", 8: "5-8", 9: "9-12", 10: "9-12"},
    gender_map={"Male": "boy", "Female": "girl"},
)

Custom question copy

child_info = s.kid_picker_question(
    question_1_text="Between {min_age} and {max_age}, how many children live in your household?",
    question_2_text="Please enter each child's age.",
    question_3_text="Please select each child's gender.",
    question_4_text="Which child can take the survey now (if any)?"
)

Notes

If no eligible children are reported, the function returns None and you should end or reroute the survey.
age_recodes are applied only to reporting/labels; underlying validation still uses raw ages.
Children with the same name are numbered only in the availability options, so each child remains separately selectable.
You can add inclusive options (e.g., "Non-binary," "Prefer not to say") via your gender list, then map to terms as needed in gender_map.
The availability question includes a fixed "None" option, so respondents are never forced to select a child.