Freeform for Craft

5.x ✓ Latest

• 5.x✓ Latest
• 4.x
• 3.xRetired
• 2.xRetired
• 1.xRetired

Plugin Store

Forms & Fields

# Fields

Overview

Overview of fields and important notes.

Field Types

The field types available in Freeform.

Favorite Fields New!

Manage a set of favorite fields to use in other forms.

Custom Field Types New!

Easily create your own custom field types.

Populating Field Options

With predefined data or other Craft Elements.

Field Encryption New!

Optionally encrypt the submitted data for each field.

# Overview

• Important Notes
• Standard Settings
• Field Encryption
• Populating Field Options
• Field Types Overview
• Favorite Fields

# Important Notes

• If you'd like to build your own custom field type, check out the guide.
• Saved fields are a snapshot of that field at the time it was saved.
• Any customizations of a Saved field or using a field from another form are specific only to the form they're adjusted in.
• Fields can be changed to other field types at any point, but be aware that data loss could occur when switching incompatible field types.
• All field types conveniently include the ability to set attributes for their labels, inputs, errors and instructions directly inside the form builder property editor.
  • This allows you to keep your hands clean of being inside formatting templates and specify one-off exceptions for fields such as readonly and autocomplete="off", etc.
  • To use single attributes like novalidate, just enter the attribute in the Attribute column and leave the Value column empty.
  • You can use anything inside the Form and Field objects as well, e.g.:
    • field.id to access Field ID.
    • form.handle to access form handle.

# Standard Settings

There is a standard number of settings available to all forms (with some exceptions). Every form field has the ability for you to do the following:

# Field Encryption ProNew in 5.0+

Each field includes the ability to optionally encrypt its submission data. Simply toggle the Encrypt field data setting inside the form builder for any field you wish to have encrypted. Freeform will take care of the rest.

For each field that is encrypted and contains submission data, the database row column will contain a prefix of encrypted: and then the encryption string. Freeform will decrypt the submission data for exports, email notifications, integrations, and viewing submission data inside the control panel and front end (if you have templates set up to show it).

# Populating Field Options

LitePro

All multi-option field types (such as Dropdown, Checkboxes, etc) can have their option labels and values automatically populated with Craft Elements or Pre-defined list options.

• Applicable Field Types
• Available Craft Elements
• Available Predefined Options

# Field Types

Freeform contains a rich set of field types to handle just about every possible scenario you might get yourself into.

# Favorite Fields

Any field can be a favorite field! If you have a number of fields that are commonly used across more than one form, such as Name, Email, etc, you can easily save them to your Favorite Fields list. If you need to edit or remove that field, you can always do that later in the manager area.

# Calculation ProNew in 5.1+

The Calculation field allows you to perform dynamic calculations based on user-input values within your forms.

# Supported Fields

The following fields can be accessed within field calculation formulas:

• Dropdown
• Hidden
• Invisible
• Number
• Opinion Scale
• Radios
• Rating
• Regex
• Text
• Textarea

# Supported Operators

Utilizing Symfony Expression Syntax, the Calculation field type empowers users to create sophisticated calculations effortlessly. From fundamental arithmetic to complex logical operations, users can employ an array of operators and functions to achieve desired outcomes.

# Arithmetic

# Example

(field1 - field2) + field3

(12 - 3) + 45 

54 

# Bitwise

# Example

field1 ^ 5

3 ^ 3

6

# Comparison

# Example

field1 >= field2

40 >= 50

false

# Logical

# Example

field1 > field2 || field1 < field3

10 > 10 || 10 < 20

true

# String

# Example 1

'Hello ' ~ firstName ~ ', ' ~ 'Welcome!'

'Hello ' ~ 'Bob' ~ ', ' ~ 'Welcome!'

Hello Bob, Welcome!

# Example 2

nameTitle ~ ' ' ~ firstName ~ ' ' ~ lastName

'Dr.' ~ ' ' ~ 'Sarah' ~ ' ' ~ 'Connor'

Dr. Sarah Connor

# Array

# Example

field1 in ['apple', 'orange', 'banana'] 

'banana' in ['apple', 'orange', 'banana'] 

true

# Numeric

# Example

field1 in 50..100

75 in 50..100

true

# Ternary

# Example

field1 == 5 ? 'yes' : 'no'

5 == 5 ? 'yes' : 'no'

yes

# Checkbox

A single checkbox field. The field.type property value is checkbox (for conditionals).

# Settings

• Specify a value (e.g. y or yes, etc).
  • Has a default value of Yes, which can be overwritten with any value you want. No matter what value is set manually on the front end, Freeform will interpret it as checked and record the value specified in the form builder.
• May be checked by default.
• Can be used as a User Select email notification.

# User Guides

• Need to display basic HTML (<b>, <i>, <a>, etc) in your option labels to add emphasis or display a link?
• Want to display single checkbox fields as a light switch toggle?

# Checkboxes Renamed in 5.0+

A group of checkboxes. The field.type property value is checkboxes (for conditionals).

# Settings

• Can specify labels (with values assumed) or labels and values (that differ).
• Can be automatically populated with select Craft Elements or Pre-defined list options.
• Can be used as a User Select email notification.
• Can be rendered vertically or horizontally.

# User Guides

• Need to display basic HTML (<b>, <i>, <a>, etc) in your option labels to add emphasis or display a link?
• Need to populate field options at template level? Check out the guide for workaround options.

# Confirm ProImproved in 5.0+

A field that allows you to force a user to re-enter a matching value for another text input field, including Password fields (e.g. "Confirm Email Address", "Confirm Password"). It runs through additional validation to make sure field values match. If not, it'll show an error. This field stores the data as well, in case that is important for your site's needs. The field.type property value is confirm (for conditionals).

# Settings

• Choose a target field to validate against, e.g. Email field.
  • Available fields must be of text input type, but don't necessarily need to be of the Text field type - you can use with Email fields, Password special fields, Phone fields, etc.

# Date & Time Pro

A complex date and/or time field. Can be used as Date only, Time only, or both. Many configuration and validation options available as well. The field.type property value is datetime (for conditionals).

# Settings

• May contain a default date value.
  • You may use now, today, 5 days ago, 2017-01-01 20:00:00, etc, which will format the default value according to the chosen format as a localized value.
• The default Freeform datepicker can be disabled and you can load your own manually in the template if you wish.
  • Freeform will automatically insert javascript in the footer/inside form (depending on settings) of the page for this fieldtype.
• Choose to have your own placeholder or have Freeform generate a placeholder based on the settings below.
• Set the date order formatting you'd like:
  • year month day, month day year, day month year
• Select if the year should be displayed/validated as 4 digits.
• Select if the day and month numbers should have a leading 0 for single digit values (e.g. August will display as 08 instead of 8).
• Choose the date separator character used between each year, month, day value:
  • None, Space (), /, -, .
• Select if time and datepicker should use 24 hour clock.
• Choose the clock separator character used to separate hours and minutes:
  • None, Space (), :, -, .
• Choose if placeholder should separate AM/PM with a space (for 12hr clock).
• Select the Min and Max dates for the date picker and validation (optional). Use static dates (e.g. 2018-11-01, 2018-11-30) or relative date strings (e.g. -10 days, +3 months).

# Notes

• For localization reference:
  • The Flatpickr date picker will automatically localize according to the locale set for your site. Locales available are only 2-letter codes like fr, de, etc. In the event you're using a locale like fr-CA or es-US, etc, Freeform will just look at the first 2 letters and use that as the locale.
  • To translate the formatting syntax error message, be sure to translate the following strings:
    • "{value}" does not conform to "{format}" format.
    • To translate the {format} rendered value to match the current locale, be sure to also translate whatever the rendered string is in the error message. For example, if you're using fr locale, and wish to have the default English DD/MM/YYYY show up as JJ/MM/AAAA, create a static translation for this manually.
• To customize the date picker appearance and behavior, please see Date Picker Events documentation.

# Templating

• initialValue
• dateTimeType (e.g. both)
• generatePlaceholder (e.g. true)
• dateOrder (e.g. ymd)
• date4DigitYear (e.g. true)
• dateLeadingZero (e.g. true)
• dateSeparator (e.g. /)
• clock24h (e.g. false)
• clockSeparator (e.g. :)
• clockAMPMSeparate (e.g. true)
• useDatepicker (e.g. true)
• minDate (e.g. five weeks ago)
• maxDate (e.g. 2024-12-31)

# Dropdown Renamed in 5.0+

A select dropdown menu field. The field.type property value is dropdown (for conditionals).

# Settings

• Can specify labels (with values assumed) or labels and values (that differ).
  • To make the first option empty, use labels and values approach with the first option having something like Please select... for the label, and leave option blank.
• Can be automatically populated with select Craft Elements or Pre-defined list options.
• Can be used as a User Select email notification.

# User Guides

• Need to populate field options at template level? Check out the guide for workaround options.
• Looking to include an additional "Other" choice that displays an input field for users to fill in their own value?

# Email Revised in 5.0+

A single-line text input field that includes additional validation to expect a valid email address as well as the possibility of attaching an email notification to it. Pair this with the Confirm special field type if you wish to have the user enter their email address twice. The field.type property value is email (for conditionals).

# Settings

• Optionally choose an email notification template (see Email Notifications documentation) to be used to send to the submitter of the form (or the email address entered in this field).
  • Users/groups need to have permissions for Notifications to create new formatting templates inside the form builder.

# Templating

• notificationId (the ID of the assigned email notification template)

# File Upload

A regular file upload field, using Craft Assets. The field.type property value is file (for conditionals).

# Settings

• Must have a Craft Asset Source location where the file will be uploaded to.
  • Does NOT work with Image Transforms.
  • Upload Location Subfolder (optional) - the subfolder path that files should be uploaded to. May contain form.handle or form.id variables or something like currentUser.id for folders based on user ID's or "now"|date("Y/m") to dynamically generate folders based on dates as well.
• Define maximum file size (in KB). Default is 2048 KB (2MB). Is subject to:
  • Craft's maxUploadFileSize setting
  • PHP memory_limit
  • PHP post_max_size
  • PHP upload_max_filesize
• Can allow a single file or multiple files to be uploaded.
  • Specify a number larger than 1 in the File Count setting to allow multiple files to be uploaded at the same time.
  • When collecting multiple files, a single input is still displayed, but allows multiple files to be uploaded (applies multiple attribute to the single file upload input).
• Select which file types can be uploaded.
  • Leaving all options unchecked will allow ALL file types.

# Notes

• In multi-page forms, if an earlier page contains file upload field(s), files will actually be uploaded before the form is officially submitted.
  • If the form is never completed, incomplete submissions are stored for 3hrs, and then are removed (along with the files) after that.
• If you wish to allow more file extensions, you will need to add the extraAllowedFileExtensions (and possibly extraFileKinds) config items to your Craft config file (config/general.php).
  • E.g. To add support for .heic image files, you can add the following to your config/general.php file:

    'extraAllowedFileExtensions' => 'heic',
    
    'extraFileKinds' => [
        'image' => [
            'extensions' => ['heic'],
        ],
    ],
    

    1
    2
    3
    4
    5
    6
    7
    
    • The extraFileKinds part will merge heic into the list of valid Image file types and treat it as such when you check off Image in the Allowed File Kinds setting for the field inside the Freeform form builder. If you do not do this, be sure to uncheck all file types in the Allowed File Kinds settings.
  • E.g. To add an assortment of extra file extensions, you add the following to your config/general.php file:

    'extraAllowedFileExtensions' => 'bim, dwg, rvt'`
    

    1
    
    • Then be sure to uncheck all file types in the Allowed File Kinds settings, unless you group these into a file kind group using the extraFileKinds setting shown above.
• If you're handling sensitive files, you may wish to choose an Asset volume without public URL's (Assets in this volume have public URLs toggle is off).

# Templating

• fileKinds (an array of allowed file kinds, e.g. image, document, audio, etc.)
• maxFileSizeKB (the numeric representation of the upload limit in kilobytes.)
• fileCount (the maximum number of allowed files to be uploaded.)
  • A number larger than 1 will allow multiple files to be uploaded at the same time.

# File Upload Drag & Drop Pro

An advanced premium javascript-based file uploading field, using Craft Assets. The field.type property value is file-dnd (for conditionals).

# Settings

• Can control the placeholder wording, e.g. Drag and drop files here, or click to upload.
• Choose a default style/theme, e.g. Light or Dark.
• Choose an accent color (this affects the default color for the field border and delete button).
• Must have a Craft Asset Source location where the file will be uploaded to.
  • Does NOT work with Image Transforms.
  • Upload Location Subfolder (optional) - the subfolder path that files should be uploaded to. May contain form.handle or form.id variables or something like currentUser.id for folders based on user ID's or "now"|date("Y/m") to dynamically generate folders based on dates as well.
• Specify the number of files allowed to upload.
• Define maximum file size per file (in KB). Default is 2048 KB (2MB). Is subject to:
  • Craft's maxUploadFileSize setting
  • PHP memory_limit
  • PHP post_max_size
  • PHP upload_max_filesize
• Select which file types can be uploaded.
  • Leaving all options unchecked will allow ALL file types.

# Notes

• Unlike the regular File Upload field, the File Upload Drag & Drop field will remember files that have been uploaded to it regardless of the context: errors upon submission, multi-page forms, returning to edit the submission later.
  • If the form is never completed, incomplete submissions are stored for 3hrs, and then are removed (along with the files) after that.
• While files are uploading, Freeform will disable the Submit button so that the form has time to finish uploading the files. If the form is submitted while files are still uploading, any that are incomplete will not be saved.
• If you wish to allow more file extensions, you will need to add the extraAllowedFileExtensions (and possibly extraFileKinds) config items to your Craft config file (config/general.php).
  • E.g. To add support for .heic image files, you can add the following to your config/general.php file:

    'extraAllowedFileExtensions' => 'heic',
    
    'extraFileKinds' => [
        'image' => [
            'extensions' => ['heic'],
        ],
    ],
    

    1
    2
    3
    4
    5
    6
    7
    
    • The extraFileKinds part will merge heic into the list of valid Image file types and treat it as such when you check off Image in the Allowed File Kinds setting for the field inside the Freeform form builder. If you do not do this, be sure to uncheck all file types in the Allowed File Kinds settings.
  • E.g. To add an assortment of extra file extensions, you add the following to your config/general.php file:

    'extraAllowedFileExtensions' => 'bim, dwg, rvt'`
    

    1
    
    • Then be sure to uncheck all file types in the Allowed File Kinds settings, unless you group these into a file kind group using the extraFileKinds setting shown above.
• If you're handling sensitive files, you may wish to choose an Asset volume without public URL's (Assets in this volume have public URLs toggle is off). However, please note that image file thumbnails will only be present directly after initial upload. Afterward (error when submitting, multi-page forms, returning to edit) the image thumbnails will no longer be accessible to Freeform.

# Templating

• fileKinds (an array of allowed file kinds, e.g. image, document, audio, etc.)
• maxFileSizeKB (the numeric representation of the upload limit in kilobytes.)
• fileCount (the maximum number of allowed files to be uploaded.)
  • A number larger than 1 will allow multiple files to be uploaded at the same time.

# Customizing the Appearance

The form builder includes some options for controlling basic styling, but you can also customize the appearance of the Drag and Drop File Upload field by using your own CSS. To avoid name collision and have maximum flexibility, the CSS class names use BEM methodology. You will also likely need to specify !important for each override to ensure it takes effect.

# CLASS NAMES Renamed in 5.0+

Below is a list of all class names listed in SCSS:

.freeform-file-dnd__input {
    &__placeholder {}
    &__messages {}
    &__preview-zone {
        &__file-preview {
            &__filename {}
            &__filesize {}
            &__thumbnail {
                &__extension-label {}
                &__remove-button {}
                &__errors {}
                &__progress {}
            }
        }
    }
}

# SCSS EXAMPLE

Below is an example with SCSS:

.freeform-file-dnd__input {
    background: blue;
  
    &__preview-zone {
        &__file-preview {
            border: 3px solid grey;
        
            &__thumbnail {
                border: 1px solid black;
                padding: 5px;
            
                &__remove-button {
                border-radius: 0;
                }
            }
        }
    }
}

# CSS EXAMPLE

Below is an example with regular CSS:

.freeform-file-dnd__input {
    background: blue !important;
    border: 1px solid red !important;
}
.freeform-file-dnd__placeholder {
    font-size: 12px !important;
}
.freeform-file-dnd__preview-zone__file-preview__thumbnail {
    border: 3px solid yellow !important;
    }
.freeform-file-dnd__preview-zone__file-preview__thumbnail__remove-button {
    border-radius: 0 !important;
}

# Group ProNew in 5.0+

A field that contains other fields within it. To use, add a Group field into your form's layout, then add/drag other fields into that Group inside the form builder. This becomes especially powerful when using with Conditional Rules, as you'll be able create a single rule to show/hide an entire group of fields at once.

# Settings

This field type only contains instructions and attributes for settings inside the builder.

# Hidden

A hidden input field.

# Settings

• Can only include text strings at this time (no variables allowed).
  • If you need you pass a value to your hidden field dynamically, you can do so with the values parameter. E.g. values: { myFieldName: "myvalue" }

# Special Notes

• To access hidden fields in GraphQL queries you have to loop through the form > fields as they are not added to form > pages > rows > fields.

# HTML

A special field type that allows you include HTML and Twig inside your form layout in the form builder. The field.type property value is html (for conditionals).

# Notes

• The Property Editor will load an HTML area for you to type or paste your code into.
• The Layout column in the form builder will live parse your HTML (Twig will not be parse inside the form builder).
• All HTML is allowed here.
• To enable Twig inside this field, turn on the Allow Twig to be Enabled for each HTML block? setting (and decide if you need to enable to the Render HTML block Twig in isolated mode? setting as well). Then, you will see an Allow Twig checkbox in the property editor column. Check that to allow this HTML block to parse Twig code.

# Display Submission Data from Previous Pages

If you'd like to display submission data from previous pages, you can do this by using an HTML block field with Twig code that might look something like this:

<ul>
    <li>Name: {{ form.get('firstName').value }} {{ form.get('lastName').value }}</li>
    <li>Email: {{ form.get('email').valueAsString }}</li>
    <li>Home Phone: {{ form.get('homePhone').value }}</li>
    <li>My Radio Field: {{ form.get('myRadioField').value }}</li>
</ul>

# Invisible Pro

A field that allows you to collect hidden data in form submissions without a hidden field being present in the template source code.

# Settings

• Can only include text strings at this time (no variables allowed).
  • If you need you pass a value to your hidden field dynamically, you can do so with the values parameter. E.g. values: { myFieldName: "myvalue" }

# Multiple Select

A multiple-select field. The field.type property value is multiple-select (for conditionals).

# Settings

• Can specify labels (with values assumed) or labels and values (that differ).
• Can be automatically populated with select Craft Elements or Pre-defined list options.
• Can be used as a User Select email notification.

# Number

A single-line number type input field that is validated to contain certain numbers only. The field.type property value is number (for conditionals).

# Settings

• Choose if validation should allow negative numbers.
• Optionally set Min/Max values.
  • You can set both, just one or neither.
• Optionally set Min/Max character length.
  • You can set both, just one or neither.
• Optionally set the number of decimals allowed.
• Set the step number to set default increments when a user uses the browser up/down arrows to increase/decrease the value.

# Templating

• minLength
• maxLength
• minValue
• maxValue
• decimalCount
• allowNegative (e.g. false)
• step

# Opinion Scale ProRevised in 5.0+

A special field that allows for flexible opinion scoring using Freeform's built in CSS. The field.type property value is opinion-scale (for conditionals). This field type is included automatically with the Pro edition of Freeform.

# Settings

• Set the field's option values and optional corresponding labels.
• Optionally add legends to correspond to with choice options (e.g. Less Satisfied, More Satisfied).

# Templating

• scales
• legends

# Customizing the Appearance

To manually render an Opinion Scale field to use your own styles, your code might look something like this:

{% set field = form.get("opinionScale") %}

<ul style="border: 1px dashed gray; padding: 5px;">
    {% for scale in field.scales %}
        <li>
            <input type="radio" name="{{ field.handle }}"
                value="{{ scale.value }}"
                id="{{ field.idAttribute }}-{{ loop.index }}"
                {{ field.value == scale.value ? "checked" }}
                class="hidden"
            />
            <label for="{{ field.idAttribute }}-{{ loop.index }}">
                {{ scale.label ?: scale.value }}
            </label>
        </li>
    {% endfor %}
</ul>

{% if field.legends %}
    <ul>
        {% for legend in field.legends %}
            <li>{{ legend }}</li>
        {% endfor %}
    </ul>
{% endif %}

# Password Pro

A special field type that allows you to securely collect a password from a submitter but NOT store the value in the Freeform database (typically used for User Registration forms with the Elements integration). Pair this with the Confirm special field type if you wish to have the user enter their password twice. The field.type property value is password (for conditionals).

# Notes

• Collected data is not stored in Freeform anywhere, nor is it included in the Submission object or allFields variable in email notifications.
• When using with the Users Element integration, the password will be passed off to Craft's Users member account feature.

# Phone Pro

A tel type input field that is validated to contain phone numbers only, based on a configured pattern. The field.type property value is phone (for conditionals).

# Settings

• Set pattern to desired format, where 0 is a digit between 0 and 9.
  • E.g. (000) 000-0000 or +0 0000 000000, etc.
  • Toggle the Use JS validation setting to have Freeform include JS in the form that validates the format and auto-inserts the extra characters like (, -, + etc).

# Templating

• pattern

# Radios Renamed in 5.0+

A group of radio options. The field.type property value is radios (for conditionals).

# Settings

• Can specify labels (with values assumed) or labels and values (that differ).
• Can be automatically populated with select Craft Elements or Pre-defined list options.
• Can be used as a User Select email notification.
• Can be rendered vertically or horizontally.

# User Guides

• Need to display basic HTML (<b>, <i>, <a>, etc) in your option labels to add emphasis or display a link?
• Need to populate field options at template level? Check out the guide for workaround options.
• Looking to include an additional "Other" choice that displays an input field for users to fill in their own value?

# Rating Pro

A special field that allows for star ratings using Freeform's built-in CSS. The field.type property value is rating (for conditionals). This field type is included automatically with the Pro edition of Freeform.

# Settings

• Set the field's number of stars (3-10).
• Style the color of the stars for the unselected, hover and selected states.

# Templating

• colorIdle (e.g. #ddd)
• colorHover (e.g. gold)
• colorSelected (e.g. #f70)
• maxValue (e.g. 5)

# Customizing the Appearance

To manually render a Rating field using your own styles, your code might look something like this:

{% for i in 1..field.maxValue %}
    <label for="rating-{{ i }}">whatever {{ i }}</label>
    <input type="radio" id="rating-{{ i }}" value="{{ i }}" name="{{ field.handle }}">
{% endfor %}

# Regex Pro

An input field that is validated based on the specified regex pattern (e.g. /^[a-zA-Z0-9]*$/). The field.type property value is regex (for conditionals).

# Settings

• Specify a required pattern for values to match, e.g. /^[a-zA-Z0-9]*$/.
  • When needing to use {} for attributes in Regex fields (such as pattern), you will need to specify them differently, as Freeform is built to allow Twig rendering and it'll choke. So for example, if you need to use [0-9]{4,5}, change it to:

    [0-9]{{ '{' }}4,5{{ '}' }}
    

    1
    
• Set the error message a user will see if an incorrect value is supplied.
  • Any occurrences of {pattern} will be replaced with specified regex pattern inside the error message, if any are found.

# Templating

• pattern
• message

# Rich Text Pro

A special field type that allows you include rich text inside your form layout in the form builder. The field.type property value is rich-text (for conditionals).

# Notes

• The Property Editor will load a Rich Text area for you to type into and style as necessary.
• The Layout column in the form builder will live parse your content.

# Signature Pro

A field that allows users to handwrite signatures with their mouse inside your form. The field.type property value is signature (for conditionals).

# Settings

• Set the dimensions of the field writing/drawing area.
• Set the border and background colors.
• Set the pen dot size (in pixels) and the color.
• To include ability for a user to click a button to erase their signature and start over, check off the Show 'Clear' button? checkbox.

# Notes

• Signatures are stored as an image datapoint value.
• Signatures can be downloaded as JPG or PNG files (from control panel).
• Signatures are excluded from regular exports and the allFields loop in email notification templates (since it would just hold an image datapoint value string).
• Signatures can be edited when the form is in edit mode.
• The Clear button can be styled inside the form builder with Input attributes area inside the property editor.
• The Signature field, due to it's complexness, cannot easily be manually generated in a form, and is best done with render helpers, e.g. field.render.
• There's currently no way to make the signature pad area "responsive" (like setting it to 100% width), as this would be quite difficult to account for with the need to display the signature image in various places, etc.

# Submit buttons Revised in 5.0+

Submit buttons are handled automatically by Freeform. They are automatically inserted at the end of your form in the form builder. This includes the Submit/Continue, Previous (where applicable), and Save & Continue Later buttons (where available).

# Settings

The Submit button settings allow you to edit the button label(s) and adjust the positioning of the buttons.

• When using with multi-page forms, Freeform will detect when you're on a page after first page, and provide you with the option to toggle a Back button.
• When using with the Pro edition, Freeform will provide you with the option to toggle a Save button.

# Templating Revised in 5.0+

Controlling the format for submit buttons is now done through the new buttons namespace available in the Template Overrides feature.

{{ form.render({
    buttons: {
        attributes: {
            container: { ... },
            column: { ... },
            buttonWrapper: { ... },
            submit: { class: "form-field-button blue" },
            back: { class: "form-field-button gray" },
            save: { class: "form-field-button blue" },
        },
        submitLabel: "Send",
        backLabel: "Previous",
        saveLabel: "Save",
    }
}) }}

# Further Customization

If the override approach above is not enough for your needs, you can use a more manual approach. First, you need to disable the automatic insertion of Submit buttons by applying the disable: ["submitButtons"] parameter to your form. Then, you can use the button render approach.

The following are available:

• renderSubmit - render a complete Submit button
• renderBack - render a complete Back button
• renderSave - render a complete Save button

{{ form.renderTag({
    returnUrl: "contact/success",
    disable: ["submitButtons"]
}) }}

    {# Your fields #}

    {% set page = form.pages.current %}

    {{ page.buttons.renderSubmit({ 'data-optional': 'attributes here' }) }}
    {% if form.pages.current.buttons.back %}
        {{ page.buttons.renderBack }}
    {% endif %}
    {% if form.pages.current.buttons.save %}
        {{ page.buttons.renderSave }}
    {% endif %}

{{ form.renderClosingTag }}

And finally, for maximum control, you can use a property attributes render instead. The following are available:

• renderSubmitProps - render the property attributes to attach to your Submit button
• renderBackProps - render the property attributes to attach to your Back button
• renderSaveProps - render the property attributes to attach to your Save button

{{ form.renderTag({
    returnUrl: "contact/success",
    disable: ["submitButtons"]
}) }}

    {# Your fields #}

    {% set page = form.pages.current %}

    <button {{ page.buttons.submitRenderProps({ 'data-optional': 'attributes here' }) }}>
        Submit
    </button>
    {% if form.pages.current.buttons.back %}
        <button {{ page.buttons.backRenderProps }}>
            Back
        </button>
    {% endif %}
    {% if form.pages.current.buttons.save %}
        <button {{ page.buttons.saveRenderProps }}>
            Save
        </button>
    {% endif %}

{{ form.renderClosingTag }}

# Save & Continue Later Pro

This feature allows users to save their form progress and continue/complete the form later. For more information about this feature, please see the Save & Continue Later documentation.

# Additional Configuration

• A return URL must be configured. This is where the user should be returned to if they click the button.
  • Special token and key variables are available to include in the return path.
  • The return URL can be wherever you like, and fully customizable. This is where you'd include instructions to the user including a URL for where to return to complete the form later.
• You may optionally specify that an email notification be sent to the user if they click the Save button.
  • Choose a special Freeform email notification template.
  • The message of this email notification is completely customizable, but be sure to include instructions to the user including a URL for where to return to complete the form later.
  • Requires targeting of an Email field that will contain the user's email address in order to send the email notification.
    • If the user hasn't yet filled out an email address, the email notification attempt will be suppressed (as there is no field validation to ensure the Email field is fillout out). A good way around this would be to have the first page include basic info like name and email but no option to save the form until the second page.

# Stripe Payment ProImproved in 5.0+

When the Stripe Payments integration is configured, a Stripe Payments special field type will become available. This field enables your forms to collect (but not store) credit card or other payment information and pass it off to Stripe.

# Table Pro

A field that allows you to collect and handle repeating data. The field.type property value is table (for conditionals).

# Settings

• Use the Table Layout area to create columns for the table. Options are:
  • Text
  • Checkbox
    • When using Checkbox, specify a value you'd like to represent that checkbox when checked.
  • Dropdown
    • When using Dropdown, specify multiples separated by the ; character, e.g. apples;oranges:cherries.
• Check off Use built-in Table JS? checkbox to have Freeform include JS in the form that validates the format and auto-inserts the extra characters like (, -, + etc).

# Rendering

Here's how you can use field.render for an automated approach to render your Table field inside your formatting templates:

{{ field.render({
    class: "table",
    label: "table-label",
    row: "table-row",
    column: "table-col",
    addButtonLabel: "Add +",
    addButtonClass: "btn btn-sm btn-primary",
    removeButtonLabel: "x",
    removeButtonClass: "btn btn-sm btn-danger",
    tableTextInputClass: "form-control",
    tableDropdownInputClass: "form-control",
    tableCheckboxInputClass: "form-check-input"
}) }}

# Customizing the Appearance

For manual rendering of the Table field inside your form for full customizability, your code might look something like this:

<table class="table">
    <thead>
        <tr>
        {% for column in field.tableLayout %}
            <th>{{ column.label }}</th>
        {% endfor %}
        </tr>
    </thead>
    <tbody>
    {% if field.value is empty %}
        <tr>
        {% for index, column in field.tableLayout %}
            {% set colName = field.handle ~ "[0][" ~ index ~ "]" %}
            <td>
            {% switch column.type|default("text") %}
                {% case "dropdown" %}
                    <select name="{{ colName }}">
                    {% for option in column.value|default("")|split(";") %}
                        <option value="{{ option }}">{{ option }}</option>
                    {% endfor %}
                    </select>
                {% case "checkbox" %}
                    <input type="checkbox" name="{{ colName }}" value="{{ column.value|default("Yes") }}" />
                {% default %}
                    <input type="text" name="{{ colName }}" value="{{ column.value|default("") }}" />
            {% endswitch %}
            </td>
        {% endfor %}
        </tr>
    {% else %}
        {% for rowIndex, row in field.value %}
            <tr>
            {% for index, column in field.tableLayout %}
                {% set colName = field.handle ~ "[" ~ rowIndex ~ "][" ~ index ~ "]" %}
                {% set colValue = row[index]|default("") %}
                <td>
                    {% switch column.type|default("text") %}
                    {% case "dropdown" %}
                        <select name="{{ colName }}">
                        {% for option in colValue|default("")|split(";") %}
                            <option value="{{ option }}"{{ option == colValue ? " selected" }}>{{ option }}</option>
                        {% endfor %}
                        </select>
                    {% case "checkbox" %}
                        <input type="checkbox" name="{{ colName }}" value="{{ column.value|default("Yes") }}" {{ colValue ? "checked" }} />
                    {% default %}
                        <input type="text" name="{{ colName }}" value="{{ colValue }}" />
                    {% endswitch %}
                </td>
            {% endfor %}
            </tr>
        {% endfor %}
    {% endif %}
    </tbody>
</table>

# Submission Data

Here's how to render a Table field's data inside the Submission object:

<table class="table">
    <thead>
        <tr>
        {% for column in field.tableLayout %}
            <th>{{ column.label|default("-") }}</th>
        {% endfor %}
        </tr>
    </thead>
    <tbody>
    {% for row in submission[field.handle].value %}
        <tr>
        {% for index, column in field.tableLayout %}
            <td>{{ row[index] }}</td>
        {% endfor %}
        </tr>
    {% endfor %}
    </tbody>
</table>

A complete example might look like:

{% for field in submission %}
    <td>
    {% if field.type == "table" %}
        <table class="table">
            <thead>
                <tr>
                {% for column in field.tableLayout %}
                    <th>{{ column.label|default("-") }}</th>
                {% endfor %}
                </tr>
            </thead>
            <tbody>
            {% for row in submission[field.handle].value %}
                <tr>
                {% for index, column in field.tableLayout %}
                    <td>{{ row[index] }}</td>
                {% endfor %}
                </tr>
            {% endfor %}
            </tbody>
        </table>
    {% else %}
        {{ submission[field.handle] }}
    {% endif %}
    </td>
{% endfor %}

# Text

A single-line text input field. The field.type property value is text (for conditionals).

# Textarea

A multi-line text input field. The field.type property value is textarea (for conditionals).

# Settings

• Can specify the number of rows the textarea should have.

# User Guides

• Need to display linebreaks for Textarea fields in email notifications or on the front end with a Submissions query?
• Want to allow users to use a rich text editor such as TinyMCE on the textarea field?

# Website Pro

A url type input field that checks to see if the URL specified has valid syntax (http://, https://, ftp://, etc). The field.type property value is website (for conditionals).

# Populating Fields with Elements & Predefined Options

LitePro

Improved in 5.0+

Inside the form builder (only), field types with options (such as Dropdown, Radios, etc) have the ability to be automatically fed options from Craft Elements or Freeform's own predefined options. This allows you to quickly build forms by having fields auto-generated.

# Applicable Field Types

The following field types can be auto-populated:

• Dropdown
  • Optional Empty Option Label to have first option be something like Please select...
• Multiple Select
• Checkboxes
• Radios

# Available Craft Elements

LitePro

The following Craft Elements can be fed to the above field types:

• Craft Entries
  • Target sections or all sections.
  • Option Label and Option Value choices:
    • ID, Title, Slug, URI, Fields (simple values)
• Craft Users
  • Target user groups or all groups.
  • Option Label and Option Value choices:
    • ID, Username, Email, First Name, Last Name, Full Name, Fields (simple values)
• Craft Categories
  • Target category groups or all groups.
  • Option Label and Option Value choices:
    • ID, Title, Slug, URI, Fields (simple values)
• Craft Tags
  • Target tag groups or all groups.
  • Option Label and Option Value choices:
    • ID, Title, Slug, URI, Fields (simple values)
• Craft Assets
  • Target product type or all product types.
  • Option Label and Option Value choices:
    • Filename, ID, Fields (simple values)
• Craft Commerce Products
  • Target asset groups or all groups.
  • Option Label and Option Value choices:
    • ID, Title, Slug, URI, SKU, Price, Fields (simple values)

# Available Predefined Options

LitePro

The following Freeform predefined options can be fed to the above field types:

• States
  • Official USA States
  • Option Label and Option Value choices:
    • Full
    • Abbreviated (upper case 2 letters)
• States & Territories
  • Official USA States and territories
  • Option Label and Option Value choices:
    • Full
    • Abbreviated (upper case 2 letters)
• Canadian Provinces
  • Provinces - English
    • Canadian Provinces and territories in English
  • Provinces - French
    • Canadian Provinces and territories in French
  • Provinces - Bilingual
    • Bilingual list of Canadian Provinces and territories
    • Option Label and Option Value choices:
      • Full
      • Abbreviated (upper case 2 letters)
• Countries
  • All world countries
  • Option Label and Option Value choices:
    • Full
    • Abbreviated (upper case 2 letters)
• Languages
  • All world languages
  • Option Label and Option Value choices:
    • Full
    • Abbreviated (lower case 2 letters)
• Numbers (range)
  • A custom range of numbers
  • Range Start and Range End
    • E.g. 60 - 65 would return list: 60, 61, 62, 63, 64, 65
• Years (range)
  • A custom range of years
  • Range Start - number of years in PAST from current year
  • Range End - number of years in FUTURE from current year
    • E.g. 5 (start) - 0 (end) would return list: 2018, 2017, 2016, 2015, 2014, 2013
  • Sort Direction:
    • Ascending
    • Descending
• Months
  • All 12 months of the year.
  • Option Label and Option Value choices:
    • Full, e.g. September
    • Abbreviated (Capitalized 3 letters), e.g. Sep
    • Single Number, e.g. 9
    • 2-digit Number, e.g. 09
• Days
  • List of days 1 to 31.
  • Option Label and Option Value choices:
    • Single Number, e.g. 3
    • 2-digit Number, e.g. 03
• Days of Week
  • List of all days of week.
  • Option Label and Option Value choices:
    • Full, e.g. Thursday
    • Abbreviated (Capitalized 3 letters), e.g. Thu
    • Single Number, e.g. 4

# Convert to Custom Options New in 5.0+

Sometimes you need a little more control over the populated data generated by the Element or Predefined options. You can click the Convert to Custom Options button at any time to have the generated option data converted to Custom options that can then have its options edited, removed, added, renamed, and reordered.