Form fields¶

All fields accept keyword-only arguments. See Collecting data with forms for usage patterns.

Common parameters¶

These parameters are available on most fields:

Parameter	Type	Default	Description
`label`	`str`	`""`	Question text shown to the participant
`optional`	`bool`	`False`	Allow empty responses
`description`	`str`	`""`	Help text below the field
`default`	any	`None`	Pre-filled value
`render_kw`	`dict`	`None`	HTML attributes for the input element
`widget`	any	`None`	Custom WTForms widget
`class_wrapper`	`str`	`None`	CSS class for the wrapper div

BooleanField¶

A single checkbox.

consent=BooleanField(label="I agree to participate")

Parameter	Type	Default
`label`	`str`	`""`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`
`validators`	list	—

BoundedChoiceField¶

Multi-select checkboxes with min/max selection limits.

topics=BoundedChoiceField(
    label="Select your preferred topics",
    choices=["Economics", "Psychology", "Sociology"],
    min=1,
    max=3,
)

Parameter	Type	Default	Description
`choices`	list or dict	—	Available options
`min`	`int`	`0`	Minimum number of selections
`max`	`int`	`None`	Maximum selections (`None` = unlimited)
`layout`	`str`	`"vertical"`	`"vertical"` or `"horizontal"`
`label`	`str`	`""`
`description`	`str`	`""`
`render_kw`	`dict`	`None`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

Returns a list of selected values.

See the bounded_choice example

DateField¶

A date picker.

birthdate=DateField(label="Date of birth")

Parameter	Type	Default
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

DecimalField¶

Decimal number input with optional addons and min/max bounds.

amount=DecimalField(
    label="Amount to contribute",
    min=0.0,
    max=100.0,
    step=0.01,
    addon_start="$",
)

Parameter	Type	Default	Description
`min`	number	—	Minimum value
`max`	number	—	Maximum value
`step`	number	—	Step increment
`addon_start`	`str`	—	Text before the input (e.g., `"$"`)
`addon_end`	`str`	—	Text after the input (e.g., `"EUR"`)
`class_addon_start`	`str`	`""`	CSS class for start addon
`class_addon_end`	`str`	`""`	CSS class for end addon
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

DecimalRangeField¶

A slider input.

confidence=DecimalRangeField(
    label="How confident are you?",
    min=0,
    max=100,
    step=1,
    label_min="Not at all",
    label_max="Completely",
)

Parameter	Type	Default	Description
`min`	number	—	Minimum value
`max`	number	—	Maximum value
`step`	number	`1.0`	Step increment
`label_min`	`str`	`None`	Label below left end (defaults to `str(min)`)
`label_max`	`str`	`None`	Label below right end (defaults to `str(max)`)
`label_max_min_class_suffix`	`str`	`"-custom"`	CSS class suffix for endpoint labels
`hide_popover`	`bool`	`False`	Hide the current value popover
`anchoring`	`bool`	`True`	Show initial slider position
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

See the input_elements example

EmailField¶

HTML email input. It checks required/optional status like other fields; add a page validate method if you need stricter server-side email validation.

email=EmailField(label="Your email address")

Parameter	Type	Default	Description
`label_floating`	`str`	`None`	Floating label inside the input
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

FileField¶

File upload. Always treated as a stealth field—process in handle_stealth_fields.

document=FileField(label="Upload your document")

See File uploads for details.

Parameter	Type	Default
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

IBANField¶

IBAN input with format validation (requires the schwifty library).

iban=IBANField(label="Your IBAN")

Parameter	Type	Default	Description
`addon_start`	`str`	—	Text before the input
`addon_end`	`str`	—	Text after the input
`class_addon_start`	`str`	`""`	CSS class for start addon
`class_addon_end`	`str`	`""`	CSS class for end addon
`label_floating`	`str`	`None`	Floating label inside the input
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

See the payment_data example

IntegerField¶

Whole number input with optional addons and min/max bounds.

age=IntegerField(label="How old are you?", min=18, max=100)

Parameter	Type	Default	Description
`min`	`int`	—	Minimum value
`max`	`int`	—	Maximum value
`addon_start`	`str`	—	Text before the input
`addon_end`	`str`	—	Text after the input
`class_addon_start`	`str`	`""`	CSS class for start addon
`class_addon_end`	`str`	`""`	CSS class for end addon
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

BICField¶

BIC/SWIFT code input with format validation (requires the schwifty library).

bic=BICField(label="Your bank's BIC")

It accepts the same addon, label, optional, rendering, and wrapper parameters as IBANField. See the payment data example.

LikertField¶

Rating scale rendered as radio buttons with labeled endpoints.

satisfaction=LikertField(
    label="How satisfied are you?",
    label_min="Very unsatisfied",
    label_max="Very satisfied",
    min=1,
    max=7,
)

Parameter	Type	Default	Description
`min`	`int`	`1`	Lowest value
`max`	`int`	`7`	Highest value
`label_min`	`str`	`""`	Label below the lowest value
`label_max`	`str`	`""`	Label below the highest value
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

Auto-generates integer choices from min to max.

RadioField¶

Choose one option with radio buttons.

choice=RadioField(
    label="Do you agree?",
    choices=[(True, "Yes"), (False, "No")],
)

Parameter	Type	Default	Description
`choices`	list, dict, or `None`	`None`	Options (defaults to `[True, False]` if `None`)
`layout`	`str`	`"vertical"`	`"vertical"` or `"horizontal"`
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

Choices can be:

list[tuple[value, label]] — e.g., [(1, "Option A"), (2, "Option B")]
dict[value, label] — e.g., {"a": "Option A", "b": "Option B"}
list[value] — e.g., [1, 2, 3] (value and label are the same)

SelectField¶

Dropdown selection.

country=SelectField(
    label="Country",
    choices=[("us", "United States"), ("de", "Germany")],
)

Parameter	Type	Default	Description
`choices`	list or dict	—	Options (required)
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

Accepts the same choice formats as RadioField.

StringField¶

Single-line text input.

participant_name=StringField(label="Your name")

Parameter	Type	Default	Description
`addon_start`	`str`	—	Text before the input
`addon_end`	`str`	—	Text after the input
`class_addon_start`	`str`	`""`	CSS class for start addon
`class_addon_end`	`str`	`""`	CSS class for end addon
`label_floating`	`str`	`None`	Floating label inside the input
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

TextAreaField¶

Multi-line text input.

comments=TextAreaField(label="Additional comments", optional=True)

Parameter	Type	Default	Description
`addon_start`	`str`	—	Text before the input
`addon_end`	`str`	—	Text after the input
`class_addon_start`	`str`	`""`	CSS class for start addon
`class_addon_end`	`str`	`""`	CSS class for end addon
`label_floating`	`str`	`None`	Floating label inside the input
`label`	`str`	`""`
`optional`	`bool`	`False`
`render_kw`	`dict`	`None`
`description`	`str`	`""`
`widget`	any	`None`
`default`	any	`None`
`class_wrapper`	`str`	`None`

See all field types in the input_elements example