Field types
Every field type — what each one collects, how it validates, and when to use it.
These are the nineteen field types a respondent can be asked for, plus three that ask nothing: heading is a section title, page-break splits the form into steps, and hidden records a value from the link rather than from the respondent. Payment fields are their own thing and are set up in the builder rather than listed here. Each field carries a label, an optional placeholder and help text, and a required flag.
| Type | Shown as | When to use it |
|---|---|---|
text | Short text | One line of free text — names, job titles, reference numbers. |
textarea | Long text | A multi-line box for anything open-ended: feedback, descriptions, questions. |
email | Validated as an email address before the form will submit. Use this rather than a text field if you plan to reply. | |
phone | Phone | Digits, formatted as the respondent types. |
url | Website | A link, validated as one. A bare example.com is accepted; anything that isn't http or https is rejected. |
address | Address | A grouped street / city / region / postcode block instead of one free-text line. |
number | Number | Numeric input only — quantities, ages, budgets. |
select | Dropdown | One answer from a list, collapsed. Best above roughly six options. |
radio | Single choice | One answer from a list, all options visible. Best for two to six options. |
checkbox | Multiple choice | Any number of answers from a list. |
ranking | Ranking | The respondent puts every option in order. The answer is the order itself, not a pick. |
rating | Star rating | One to five stars — satisfaction, quality, how it went. Set a different ceiling if five is wrong. |
scale | Opinion scale | A numbered scale with a caption at each end. The 0–10 default is the standard NPS question. |
date | Date | A native date picker — no format ambiguity between regions. |
time | Time | A native time picker, for appointments and slots. Pair it with a date field. |
file | File link | A URL pointing at a file the respondent already hosts. |
upload | File upload | The respondent uploads the file itself; it is stored with the response. |
signature | Signature | A drawn signature, for consent and acknowledgement forms. |
appointment | Appointment | The respondent picks a real open slot from your recurring availability — not just a date or time, an actual booking that can't be double-booked. |
heading | Section heading | Display only — collects no answer. Use it to break a long form into named sections. |
page-break | Page break | Display only — collects no answer. Splits the form into steps with a progress bar, one page per break. |
hidden | Hidden field | Renders nothing. Captures a query parameter from the link the respondent arrived on — ?utm_source=newsletter lands in the export. |
Choice fields
select, radio, checkbox, and ranking all take an options array of strings. radio and select both accept exactly one answer — the difference is whether the options are visible up front. Show them when there are few, collapse them when there are many.
ranking is the odd one: the respondent does not pick an option, they put all of them in order, and the stored answer is that order. Mark it required and every option has to be placed.
Ratings and scales
rating and scale are the same question — pick one number from a short range — drawn two ways, and they share the same settings. scaleMax is how many stars a rating offers (five by default) or where a scale tops out. A scale also takes scaleMin (0 or 1) and a caption for each end, scaleMinLabel and scaleMaxLabel.
The default scale is the standard Net Promoter question: 0 to 10, “Not likely” to “Very likely”. Set the captions on any scale you change — a bare row of numbers does not tell the respondent which end is the good one. Either type accepts at most eleven points; past that they stop being tappable on a phone, which is where most forms get answered.
Required fields and validation
Set required: true and the form will not submit without an answer. Type-level validation runs on top of that: email must look like an address, number rejects text, date and time use native pickers, url must be an http or https link, and a rating or scale answer has to be a number that was actually on the scale. Validation runs in the browser and again on the server, so a crafted request cannot slip past it.
Requiring everything is the most common mistake. Every required field is another reason to abandon the form — mark only what you genuinely cannot act without.
Sections
A heading field renders as a section title in the flow of the form. Use them once a form covers more than one topic — Contact details, Your project, Consent. Do not open a form with a heading that repeats its title; the title already renders above the fields.
Ordering
Every field has an order number, which is what the renderer sorts on. In the studio you drag; over MCP you set it explicitly — and since update_form replaces the whole array, send fields back with their orders already correct.