Field Reference

The palette offers 49 field types: 38 from the Form plugin and 11 Pro fields that Forms Pro adds. This page lists them with the YAML key behind each setting, so you can build in the builder or write the file by hand. Property names in bold are the labels you see in the property panel.

A field in the YAML is a map under fields:, keyed by its Field Name:

fields:
  email:
    type: email
    label: Email
    validate:
      required: true

Keys every input field shares

Most input fields take these keys. The builder shows them in the General, Validation and Advanced sections.

Layout fields take the class and ID keys and conditions, but no label or validation.

Fields from the Form plugin

These work as the Form plugin documents them. The table lists the keys the builder offers. Anything else the Form plugin supports can still be written by hand.

Basic

price:
  type: number
  label: Price
  validate:
    min: 0
    step: 0.01

Choice

topic:
  type: select
  label: Topic
  placeholder: Choose one
  options:
    sales: Sales
    support: Support

The stored answer is the option key (sales), and entries and emails show its label (Sales). A Dropdown with Allow Multiple switched on (multiple: true) stores a list. Logic rules compare against the keys. A grouped dropdown writes its options as a list of groups:

region:
  type: select_optgroup
  label: Region
  options:
    - Europe:
        uk: United Kingdom
        de: Germany
    - Americas:
        us: United States
        ca: Canada

Date and time

These use the browser's own pickers. For a calendar with a chosen format and limits, see the Date Picker and Time Picker below.

Uploads

attachment:
  type: file
  label: Attachment
  destination: 'user-data://uploads'
  random_name: true
  avoid_overwriting: true
  filesize: 2
  accept:
    - 'image/*'
    - application/pdf

accept lists MIME types, filesize is in megabytes, and limit is the most files allowed when multiple is on. A new File Upload field starts with destination: 'user-data://uploads' and both name options on. The form needs the Process Uploads action (upload: true) to move the files from where they wait to the destination (see Actions and notifications). Entries covers how uploads show up in an entry.

Layout and other fields

A Conditional Group is not the same as the visibility rules on the Logic tab. Its condition is a Twig expression evaluated on the server when the form is rendered, such as config.site.title == 'Demo', and it shows or hides the whole group for everyone. Rules on the Logic tab react to what the visitor types.

A Signature field stores a PNG as a data URL, and the server refuses anything else or anything over 512 KB. It stores an image, so it is shown as a picture in entries.

Pro fields

The eleven Pro fields are marked with a sparkle in the palette. Each one below shows the YAML and what it stores.

Name field

pro-name is a name in parts. Switch the parts on and off under Options.

full_name:
  type: pro-name
  label: Name
  subfields:
    prefix: true
    first: true
    middle: false
    last: true
    suffix: false
  placeholder_first: First
  placeholder_last: Last
  validate:
    required: true

The prefix menu offers Mr., Mrs., Ms. and Dr., and the server refuses any other value. Required asks for the first and last name, for the parts that are shown. The answer is stored as a map, and entries and emails show it as Dr Grace Hopper:

full_name:
  prefix: Dr
  first: Grace
  last: Hopper

In a merge tag, reach one part with {{ form.value.full_name.first }}. In the subfields map, first and last name show unless you set them to false, and the prefix, middle name and suffix show only when set to true. The builder always writes the map out in full.

Address

pro-address collects an address in parts.

home:
  type: pro-address
  label: Address
  layout: inline
  subfields:
    street: true
    street2: true
    city: true
    state: true
    zip: true
    country: false
  placeholder_street: 123 Main St

Required asks for the street and the city, for the parts that are shown. The answer is stored as a map with the keys street, street2, city, state, zip and country. Country is a text box, not a list.

Phone

pro-phone is a phone number with an optional country selector.

mobile:
  type: pro-phone
  label: Mobile
  show_country_code: true
  default_country: GB
  placeholder: '07700 900123'

With the country selector the answer is a map:

mobile:
  country: US
  number: '555 010 4477'

The number must hold at least seven digits, unless you set a pattern, in which case it must match the pattern. The pattern is written without delimiters, such as ^\+?[0-9 ]{7,15}$. Entries and emails show the dial code in front, as +1 555 010 4477.

Without the country selector the answer is the number as plain text, '555 010 4477'. Either way it shows as readable text in emails, {{ all_fields }}, the entry view and the CSV export.

Rating

pro-rating is a row of stars, hearts, thumbs or circles.

satisfaction:
  type: pro-rating
  label: How did we do?
  max: 5
  icon: heart
  allow_half: true
  show_value: true

The answer is a number from 0 to the maximum. A rating that was never set is 0. An optional rating left unset passes whatever the minimum is, and a required one is refused until the visitor picks at least one star. The minimum applies to any rating the visitor gives.

Slider

pro-slider is a range slider that shows its value.

budget:
  type: pro-slider
  label: Budget
  min: 0
  max: 5000
  step: 250
  default: 1000
  prefix: '$'

The server refuses a value outside the minimum and maximum.

Rich Text

pro-richtext is a small formatted-text editor that runs from the plugin's own files, with no outside editor library.

notes:
  type: pro-richtext
  label: Notes
  toolbar: standard
  min_height: 120px

The answer is HTML, and the server cleans it before anything uses it. Only p, br, strong, em, b, i, u, s, ul, ol, li, a, h1 to h6, blockquote, code, pre and span survive. Every attribute is removed except href on a link, and a link only keeps its address when it starts with http:, https:, mailto:, tel:, / or #. Scripts, styles and frames are removed with their content. In emails and entries the cleaned HTML is shown formatted, and in a plain-text email it becomes text.

Date Picker

pro-datepicker is a calendar date picker.

visit_date:
  type: pro-datepicker
  label: Visit date
  format: Y-m-d
  min_date: today
  max_date: '2027-12-31'
  disable_weekends: true

The server refuses a date the calendar does not have, and a date before min_date or after max_date. The answer is stored as typed, in the chosen format.

Time Picker

pro-timepicker is a time picker.

visit_time:
  type: pro-timepicker
  label: Visit time
  time_24hr: true
  minute_increment: 15
  min_time: '09:00'
  max_time: '17:00'

Like the Date Picker, it uses Flatpickr when the page loads it and the browser's time input when not. In the browser input the minute step, the limits and the 12-hour format do not apply. The server accepts HH:MM, HH:MM:SS and, for 12-hour fields, h:mm AM, and refuses anything else. It does not check min_time and max_time.

Calculation

pro-calculation is a read-only value worked out from a formula. It is covered in Calculations and the Formula reference.

total:
  type: pro-calculation
  label: Total
  formula: 'quantity * price'
  prefix: '$'

Recipients

pro-recipients lets the visitor choose who receives the email, without any address reaching the browser. How to use the choice in an email is covered in Actions and notifications.

department:
  type: pro-recipients
  label: Send to
  display: select
  recipients:
    sales:
      label: Sales
      email: s[email protected]
    support:
      label: Support
      email: s[email protected]

The answer stored with the entry is the choice's key, or a list of keys with multiple: true. A visitor can only send one of the keys, and any other value is refused. Use short keys without spaces, because they are what shows in {{ form.value.department }}. Entries, emails and the CSV export show the labels of the chosen entries, joined with commas.

The builder has a Recipients list editor in the property panel for adding choices, labels and addresses.

With several choices, the notification goes to the addresses of every chosen entry. The addresses still come only from the form's definition on the server, never from what the visitor posts.

Repeater

pro-repeater lets visitors add the same group of fields as many times as they need, such as the lines of an order or the people on a booking.

attendees:
  type: pro-repeater
  label: Attendees
  min: 1
  max: 5
  add_label: Add attendee
  item_label: Attendee
  sortable: true
  fields:
    attendee_name:
      type: text
      label: Name
      validate:
        required: true
    attendee_email:
      type: email
      label: Email

Drag the fields that repeat into the Repeater on the canvas. They can be any fields except another Repeater, Columns, Tabs or steps. The answer is a list of maps, one per row, keyed by the fields' names:

attendees:
  -
    attendee_name: Grace
    attendee_email: g[email protected]
  -
    attendee_name: Ada
    attendee_email: ''

The server checks every row against the fields it holds: Required fields must be filled, choices must be one of the options, numbers must be numbers and within their limits, and Pro fields get their usual checks. A problem is reported with its row (Attendees, row 2: Name is required). A row with a key the Repeater has no field for is refused. Entries show a Repeater as a table, and emails as a readable list.

A Calculation inside a Repeater is worked out for each row. See Calculations.

Steps

pro-steps and pro-step split a form into pages. They are not in the palette: the builder adds them when you choose Convert to multi-step. See Multi-step forms.

Related

• The builder
• Conditional logic
• Calculations
• Extending for adding your own fields