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 or searched upon to be reused in other forms.
Overview
Important Notes
- Only Freeform's field types may be used in forms. Craft fields or custom field types are not supported at this time.
- Fields can be created and managed in the main field creation area (Freeform > Fields > New Field) and can also be created directly within the form builder interface as well. Fields created here are available globally as well (they do not just exist for that form).
- When the fields are edited at global level (in main Fields area of Freeform control panel), your customizations per form will NOT be lost.
- Once a field is created, you cannot change the field type after.
- All field properties can be overwritten at form level inside the form builder, including the field Handle.
- All fieldtypes 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 | Description |
---|---|
Reset (button) | Pressing this will reset the field settings and values back to what is set in the defaults (Freeform > Fields > New Field). |
Handle | How the field may be called in templates, if necessary. You may also override this value per form if you wish. Non-fields like HTML blocks will have a hash value that behaves the same as field handles. |
Label | The label for the field. This can be changed per form if you wish. |
Required | Mark if the field requires a value to submit the form successfully. |
Instructions | Specify intructions for the field if you wish. |
Default Value | For applicable fields, you can set a default value or selected option for the field. |
Placeholder | Specify placeholder text for the field, if applicable. |
Maximum Length | The maximum number of characters for the field's value. |
Attribute Editor | Apply any kind of attribute on the input, label, error, instruction in Freeform's automated rendering of the form. |
Populating Field Options
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.
Field Type | Description | Lite | Pro |
---|---|---|---|
Checkbox | A single checkbox field | ✓ | ✓ |
Checkbox Group | A group of checkboxes | ✓ | ✓ |
Date & Time | A complex date and/or time field | ✓ | |
Dynamic Recipients | A select/radio/checkbox field that allows the form submitter to choose from a list of available protected email addresses | ✓ | ✓ |
A text input field that includes additional email validation and possibility for attaching an email notification to it. | ✓ | ✓ | |
File Upload | A regular file upload field | ✓ | ✓ |
File Upload Drag & Drop | An advanced premium javascript-based file uploading field | ✓ | |
Hidden | A single-line hidden input field | ✓ | ✓ |
Invisible | 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 | A multiple-select field | ✓ | ✓ |
Number | A single-line number type input field that is validated to contain certain numbers only | ✓ | ✓ |
Opinion Scale | A special field that allows for flexible opinion scoring | ✓ | |
Phone | A tel type input field that is validated to contain phone numbers only, based on a configured pattern | ✓ | |
Radio Group | A group of radio options | ✓ | ✓ |
Rating | A special field that allows for star ratings | ✓ | |
Regex | An input field that is validated based on the specified regex pattern (e.g. /^[a-zA-Z0-9]*$/ ) | ✓ | |
Select | A select dropdown menu field | ✓ | ✓ |
Signature | A field that allows users to handwrite signatures inside your form | ✓ | |
Table | A field that allows you to collect and handle repeating data | ✓ | |
Text | A single-line text input field | ✓ | ✓ |
Textarea | A multi-line text input field | ✓ | ✓ |
Website | A url type input field that checks to see if the URL specified has valid syntax | ✓ |
Special Field Types
Special fields are ones that are not created, but serve a special purpose for your forms. Some of them may be reused as many times in the same form as you like.
Field Type | Description | Usage | Lite | Pro |
---|---|---|---|---|
Confirm | A text input field that targets another similar field and ensures the values match | Unlimited | ✓ | |
Credit Card | A set of input fields to allow the validation of credit cards for Stripe Payment implementations | 1 per form | ✓ | |
HTML | A block that allows you to insert HTML into areas of your form | Unlimited | ✓ | ✓ |
Email Marketing | A special checkbox to handle subcription to mailing lists when using Email Marketing integrations | Unlimited | ✓ | |
Password | A text input field that collects sensitive passwords but does not store them | Unlimited | ✓ | |
Captcha | A special field to handle spam verification when using the reCAPTCHA v2 Checkbox or hCaptcha Checkbox implementation | 1 per form | ✓ | ✓ |
Rich Text | A block that allows you to insert rich text into areas of your form (headings, descriptions, etc) | Unlimited | ✓ | |
Save & Continue Later | A special button that allows the user to save form progress and return later | 1 per page | ✓ | |
Submit | A regular submit button for the form | 1 per page | ✓ | ✓ |
Checkbox
A single checkbox field. The field.type
property value is checkbox
(for conditionals).
Form Builder Settings
- Specify a value (e.g.
y
oryes
, 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.
Templating Properties
options
(an array of option objects withlabel
andvalue
properties)
Checkbox Group
A group of checkboxes. The field.type
property value is checkbox_group
(for conditionals).
Form Builder 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 rendered vertically or horizontally.
Templating Properties
options
(an array of option objects withlabel
andvalue
properties)
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).
Form Builder Settings
- May contain a default 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.
- You may use
- 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 as08
instead of8
). - 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
).
Special 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 likefr-CA
ores-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 usingfr
locale, and wish to have the default EnglishDD/MM/YYYY
show up asJJ/MM/AAAA
, create a static translation for this manually.
- The Flatpickr date picker will automatically localize according to the locale set for your site. Locales available are only 2-letter codes like
- To customize the date picker appearance and behavior, please see Date Picker Events documentation.
Templating Properties
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
)
Dynamic Recipients
A special field, displayable as a Select, Radio or Checkbox Group that contains protected email addresses and labels for each. The field.type
property value is dynamic_recipients
(for conditionals).
Form Builder Settings
- Can specify labels and email address values.
- Multiple email addresses can be specified for each option, separated by commas.
- Emails are never parsed in source code (they're replaced with 0, 1, 2, etc).
- When parsing this field semi-manually, be sure to use
loop.index0
to generate numeric values of options instead offieldName.value
.
- When parsing this field semi-manually, be sure to use
- To make the first option empty (when displaying as Select), set 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 switched to display as Radio or Checkbox options at form level inside the form builder.
- Can be rendered vertically or horizontally.
- Choose an email notification template to be used to send to the option(s) chosen.
- Users can specify 1 or more recipient options at a time (when using as Checkboxes).
- Users/groups need to have permissions access for Email Notifications to create new formatting templates inside the form builder.
Special Notes
- Can include more than 1 of this field type in your forms, allowing for multiple sets of recipients to be notified.
- When parsing this field semi-manually, be sure to use
loop.index0
to generate numeric values of options instead offieldName.value
.
Make sure that each option value is unique.
If you're receiving duplicate or multiple email notifications from the Dynamic Recipients field, it's likely because you've specified more than one option with the same email address. This is a current limitation of Freeform, as it will perceive the user submitting all of the matching options at once, sending off emails as many times as there are duplicate options.
The only workarounds for this would be to either:
- Create an email address alias for each option so that each option in the Dynamic Recipients field type settings will be unique.
- Add sub-address tags to the affected email addresses so their values are unique. For example:
joe+whatever@example.com
,joe+somethingelse@example.com
.
Templating Properties
showAsRadio
- A boolean value. If
true
the dynamic recipients field should be rendered as radio buttons instead of a select field.
- A boolean value. If
showAsCheckboxes
- A boolean value. If
true
the dynamic recipients field should be rendered as checkboxes instead of a select field.
- A boolean value. If
notificationId
- The database ID of the assigned Email Notification Template.
Email
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).
It is required to use the Email field type if you wish for your users to receive an email notification when submitting the form and/or you're using an Email Marketing API integration.
Form Builder Settings
- Optionally choose an email notification template 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 access for Email Notifications to create new formatting templates inside the form builder.
Templating Properties
placeholder
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).
Form Builder 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
orform.id
variables or something likecurrentUser.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).
- Specify a number larger than
- Select which file types can be uploaded.
- Leaving all options unchecked will allow ALL file types.
Special 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 yourconfig/general.php
file:'extraAllowedFileExtensions' => 'heic',
'extraFileKinds' => [
'image' => [
'extensions' => ['heic'],
],
],- The
extraFileKinds
part will mergeheic
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.
- The
-
E.g. To add an assortment of extra file extensions, you add the following to your
config/general.php
file:'extraAllowedFileExtensions' => 'bim, dwg, rvt'`
- 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.
- 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
-
E.g. To add an assortment of extra file extensions, you add the following to your
config/general.php
file:'extraAllowedFileExtensions' => 'bim, dwg, rvt'`
- 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.
Before Freeform 4.1.10:
If you're still getting aUnknown file type
error, this is likely because Freeform also includes its own layer of file security checks (/vendor/solspace/craft-freeform/packages/plugin/src/Library/Helpers/FileHelper.php
). You can modify this core file to get it working for you, but please contact us if there's a missing file extension/mime type that needs to be added to Freeform and we'll likely add support for it.In Freeform 4.1.10+: Improved 4.1.10+
The above error should no longer be an issue as Freeform File Upload fields were realigned with Craft's file kind/extensions defaults and we removed the custom Freeform MIME type checks. - 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
-
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).
-