Field types

Every field is an object in the form’s fields list with at least a key and a type. This page lists the 13 types, the properties they share, and the properties specific to each.

{"key": "email", "type": "email", "label": "Email", "required": true}

Properties every field shares

Property	What it does	Default
key	Required. The field’s name in entries, emails, exports and webhooks. Unique within the form. Start with a letter; use letters, numbers and underscores (first_name).	—
type	Required. One of the 13 types below.	—
label	The text shown with the field.	none
placeholder	Grey hint text inside the field.	none
required	The visitor must fill it in.	false
description	Help text under the field.	none
default	The value the field starts with.	empty
css_class	An extra CSS class on the field’s wrapper.	none
column	Width when fields sit side by side. See Layout and steps.	full width
section	The key of the section the field belongs to.	none
step	The key of the step the field belongs to, in a multi-step form.	none
conditions	Show the field only when rules match. See Conditional logic.	always shown

The one-line fields (text, email, tel, date and address) also take maxlength, minlength, readonly, disabled and autocomplete (except address, which turns the browser’s own autocomplete off).

Use the same keys across forms for the same information (name, email, phone, message), so automations and exports line up.

The 13 types

Type	What the visitor sees	Specific properties
text	A one-line text box.	pattern — a regular expression the value must match.
email	A text box that must hold a valid email address.	—
tel	A phone number box. Accepts digits, spaces, +, - and brackets, with at least 7 digits.	pattern replaces the default character check in the browser.
textarea	A multi-line text box.	rows (default 5), cols, maxlength, minlength.
select	A dropdown.	options (required), placeholder, multiple.
radio	A set of radio buttons; one choice.	options (required), inline to lay them out in a row.
checkbox	Without options, one tick box. With options, a group where several can be ticked.	options, inline.
file	A file picker.	allowed_types, max_size, multiple. See below.
date	The browser’s date picker. Stored as YYYY-MM-DD.	min, max. See below.
address	A text box with Google address suggestions.	country_restriction. See below.
hidden	Nothing. Sends a value with the submission.	default, which can use tokens. See below.
message	A block of text or notice; not an input and not submitted.	content, style. See below.
section	A heading that groups the fields after it.	label, description. See Layout and steps.

Options for select, radio and checkbox groups

Each option is either a plain string, used as both value and label, or an object with a stored value and a displayed label:

"options": [
  {"value": "repair", "label": "Repair or service"},
  {"value": "install", "label": "New installation"},
  "Other"
]

Entries store the value. Notification emails, the entries screen and CSV exports show the label.

Important

Give every required single select a placeholder, such as "Choose one…". Without one, the browser preselects the first option, so required can never fail and a visitor who skips the question submits option one. The placeholder is an empty first option the visitor must change.

File uploads

Property	What it does	Default
allowed_types	File extensions accepted, without dots: ["pdf", "jpg", "png"].	pdf, jpg, jpeg, png, gif, doc, docx
max_size	Largest file in bytes (5242880 is 5 MB).	5 MB
multiple	Allow several files in one field.	false

The allowed types and maximum size are shown under the field. If your server’s own upload limit is lower than max_size, the lower number is shown and used. The visitor’s browser checks the type and size as soon as a file is chosen, so a file that is too large is caught before it is sent.

All files in one submission together may be as large as the file fields’ limits added up, and never less than 25 MB. Files in a field hidden by a condition are not sent or kept.

Design files (.ai, .eps, .dst, .svg) are accepted when you list them. EPS files with a preview image work. SVG is accepted only on a field that lists it, and an SVG that contains scripts or links to other files is refused.

How files are checked

Before a file is saved, the plugin checks what it really is, not just its name:

• the extension must be in allowed_types, and program files such as .php are always refused;
• the file must really be that type. A PNG named .jpg is saved as .png when both are allowed, and refused when only .jpg is;
• images must open, and no file may contain PHP code.

A refused file gets a message that says what to do, such as This file contains program code, which we cannot accept for security reasons. Please export it again, or send a PDF or PNG instead. See Validation messages. For where files are kept, see Entries.

Date

min and max limit the dates the picker offers and the server accepts. Write them as YYYY-MM-DD, or as a relative date such as "today", which is worked out each time the form is shown.

Address

Suggestions need a Google Places key in Form Entries → Settings. Without one the field is a plain text box, and administrators see a notice under it. country_restriction limits suggestions to countries, as two-letter codes: ["us", "ca"]. The address text the visitor ends up with is what is stored.

Hidden

A hidden field’s default can include these tokens, filled in when the page loads: {page_url}, {referrer}, {post_id}, {user_id}, {user_email}, {user_name}, {date} and {timestamp}. Visitors can see and change a hidden value in the page source, so do not rely on it for anything secret.

Message

content takes simple HTML: paragraphs, line breaks, bold, italic, links, lists, span, div and headings. Other tags are removed. style adds a coloured notice: info, warning, success or error. label adds a heading. Messages never appear in entries or emails.

Limits and common problems

• A required single tick box shows Check this box to continue. when left empty; use it for consent.
• Use lowercase snake_case keys. Up to version 1.10.0, conditions that refer to a key with capital letters never match.
• Phone numbers are not checked against a country format, only for allowed characters and at least 7 digits.

Related pages

• Creating and editing forms — The Forms screen, form ID rules, the parts of a form's JSON and every form-level setting.
• Layout and steps — Put fields side by side in columns, group them in sections, and split a long form into steps with a progress indicator.
• Conditional logic — Show a field or section only when another answer calls for it, with every operator and how hidden fields are treated.
• Validation messages and errors — Every message a visitor can see when a submission is refused, and the errors shown when a form's JSON cannot be saved.