Fields
Freeform features its own set of robust field types. The form builder displays a list of available field types which can then be added to forms indefinitely. Fields are specific to each form, but can also be saved as favorites or searched upon to be reused in other forms.
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
andautocomplete="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.
- This allows you to keep your hands clean of being inside formatting templates and specify one-off exceptions for fields such as
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:
Setting | Template Usage | Description |
---|---|---|
Label | label | The label for the field. This can be changed per form if you wish. |
Handle | handle | How the field may be called in templates, if necessary. You may also override this value per form if you wish. |
Required | required | Toggle if the field requires a value to submit the form successfully. |
Custom Validation ErrorNew in 5.7+ | Visible when Required is toggled on. If this field is left empty upon submit, show this error message. | |
Instructions | instructions | Specify intructions for the field if you wish. |
Default Value | defaultValue | For applicable fields, you can set a default value or selected option for the field. |
Placeholder | placeholder | Specify placeholder text for the field, if applicable. |
Maximum Length | maxlength | The maximum number of characters for the field's value. Applicable only to the following field types: |
Attribute Editor | Apply any kind of attribute on the input, label, error, instruction in Freeform's automated rendering of the form. | |
Options | options
| Specify the option labels and values for applicable field types. Available only for the following field types: |
Field EncryptionProNew 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).
Encryption is not retroactive. Each submission will need to be resaved to update older submissions.
Populating Field OptionsLitePro
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.
Field Types
Freeform contains a rich set of field types to handle just about every possible scenario you might get yourself into.
Name | field.type | Description | Express | Lite | Pro |
---|---|---|---|---|---|
CalculationNew in 5.1+ | calculation | Perform dynamic calculations based on user-input values within forms. | ✕ | ✕ | ✓ |
Checkbox | checkbox | A single checkbox field. | ✓ | ✓ | ✓ |
Checkboxes | checkboxes | A group of checkboxes. | ✓ | ✓ | ✓ |
Confirm | confirm | A text input field that targets another similar field and ensures the values match. | ✕ | ✕ | ✓ |
Date & Time | datetime | A complex date and/or time field. | ✕ | ✕ | ✓ |
Dropdown | dropdown | A select dropdown menu field. | ✓ | ✓ | ✓ |
email | A text input field that includes additional email validation and possibility for attaching an email notification to it. | ✓ | ✓ | ✓ | |
File Upload | file | A regular file upload field. | ✓ | ✓ | ✓ |
File Upload Drag & Drop | file-dnd | An advanced javascript-based file uploading field. | ✕ | ✕ | ✓ |
GroupNew in 5.0+ | group | A field that contains other fields within it. | ✕ | ✕ | ✓ |
Hidden | N/A | A hidden input field. | ✓ | ✓ | ✓ |
HTML | html | A block that allows you to insert HTML into areas of your form. | ✓ | ✓ | ✓ |
Invisible | N/A | A field that allows you to collect hidden data in form submissions without a hidden field being present in the template source code. | ✕ | ✕ | ✓ |
Multiple Select | multiple-select | A multiple-select field. | ✓ | ✓ | ✓ |
Number | number | A number type input field that is validated to contain certain numbers only. | ✓ | ✓ | ✓ |
Opinion Scale | opinion-scale | A special field that allows for flexible opinion scoring. | ✕ | ✕ | ✓ |
Password | password | A text input field that collects sensitive passwords but does not store them. | ✕ | ✕ | ✓ |
Phone | phone | A tel type input field that is validated to contain phone numbers only, based on a configured pattern. | ✕ | ✕ | ✓ |
Radios | radios | A group of radio options. | ✓ | ✓ | ✓ |
Rating | rating | A special field that allows for star ratings. | ✕ | ✕ | ✓ |
Regex | regex | An input field that is validated based on the specified regex pattern (e.g. /^[a-zA-Z0-9]*$/ ). | ✕ | ✕ | ✓ |
Rich Text | rich-text | A block that allows you to insert rich text into areas of your form (headings, descriptions, etc). | ✕ | ✕ | ✓ |
Signature | signature | A field that allows users to handwrite signatures inside your form. | ✕ | ✕ | ✓ |
Stripe PaymentImproved in 5.0+ | stripe | A set of input fields to allow the validation of credit cards and other payment options for Stripe Payment implementations. | ✕ | ✕ | ✓ |
Submit buttons | N/A | Handles the submit button(s), including Save option for the form. | ✓ | ✓ | ✓ |
Table | table | A field that allows you to collect and handle repeating data. | ✕ | ✕ | ✓ |
Text | text | A single-line text input field. | ✓ | ✓ | ✓ |
Textarea | textarea | A multi-line text input field. | ✓ | ✓ | ✓ |
Website | website | A url type input field that checks to see if the URL specified has valid syntax. | ✕ | ✕ | ✓ |
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.
CalculationProNew in 5.1+
The Calculation field allows you to perform dynamic calculations based on user-input values within your forms.
For the Calculation field to work as a dynamic amount with the Stripe Payments integration, the Input Type setting should be set to Regular Text Input or Plain Text. If set to Hidden, the Calculation field should be within a multipage setup where it is on a page before the page with the Stripe Payment Element field.
Decimal CountNew in 5.6+
The Decimal Count setting allows you to set the maximum number of decimal places the calculated result should have. Leave blank if you don't want to limit the decimal places. If you'd like to have no decimals (whole numbers only), enter a value of 0
.
Supported Fields
The following fields can be accessed within field calculation formulas:
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
Operator | Description |
---|---|
+ | Addition |
- | Subtraction |
* | Multiplication |
/ | Division |
Example
- Formula
- Values
- Output
(field1 - field2) + field3
(12 - 3) + 45
54
Comparison
Operator | Description |
---|---|
== | Equal |
=== | Identical |
!= | Not equal |
!== | Not identical |
< | Less than |
> | Greater than |
<= | Less than or equal to |
>= | Greater than or equal to |
matches | Regex match |
Example
- Formula
- Values
- Output
field1 >= field2
40 >= 50
false
Logical
Operator | Description |
---|---|
! or not | Not |
&& or and | And |
|| or or | Or |
Example
- Formula
- Values
- Output
field1 > field2 || field1 < field3
10 > 10 || 10 < 20
true
String
Operator | Description |
---|---|
~ | Concatenation |
Example 1
- Formula
- Values
- Output
'Hello ' ~ firstName ~ ', ' ~ 'Welcome!'
'Hello ' ~ 'Bob' ~ ', ' ~ 'Welcome!'
Hello Bob, Welcome!
Example 2
- Formula
- Values
- Output
nameTitle ~ ' ' ~ firstName ~ ' ' ~ lastName
'Dr.' ~ ' ' ~ 'Sarah' ~ ' ' ~ 'Connor'
Dr. Sarah Connor
Array
Operator | Description |
---|---|
in | Contains |
not in | Does not contain |