Plugin Settings
Freeform includes a wide variety of settings that allow you to customize your form management experience. To adjust your settings, click the Settings menu item while in the Freeform plugin, or go to Settings → Plugins → Freeform and click the settings link. These can also be configured within your Craft Project Config file
General Settings
Configure Freeform's overall behavior.
Form Behavior
Configure how forms behave in front end templates.
Form Builder
Configure Freeform's form builder experience.
Template Manager
Configure directory paths for Formatting, Email, and Success templates.
PDF Templates
Create custom PDF templates to be generated for email notifications.
Spam Protection
Configure Freeform's built-in spam controls.
Captchas
Enable and setup reCAPTCHA or hCaptcha for your site.
Integrations
All integrations available to Freeform.
Statuses
Manage statuses for your Freeform submissions.
Demo Templates
Install the demo templates to get up and running in seconds.
Notices & Alerts
Email Alerts, Update Notices, and Weekly Digest.
Error Log
Check out any potential problems Freeform has logged.
General Settings
Configure general settings for Freeform.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Custom Plugin Name | pluginName: 'Forms' | Override the plugin name by specifying your own here. | ✕ | ✕ | ✓ |
| Default view | defaultView: forms | Allows you to specify which Freeform page should be loaded by default when clicking the Freeform navigation link. Options are: Forms (default) and Submissions | ✓ | ✓ | ✓ |
| Plugin Badge | badgeType: all | Select the options you'd like to be included in the plugin badge count (when applicable). Options are: Don't Show, Update Notices & Logged Errors (default), Update Notices only, Logged Errors only, Submission Count, Spam Folder Count | ✓ | ✓ | ✓ |
| Site-Aware FormsNew in 5.2+, Improved in 5.7+ | sitesEnabled: true | Allows you to optionally enable Site awareness in Freeform to show/hide them for specific Sites and enable translations per site for forms to have unique labels and messages on the front end. | ✕ | ✕ | ✓ |
| Queue Job PriorityNew in 5.5.6+ | queuePriority: 20 | Set the queue job priority for background Freeform tasks to determine if they should run with a different priority compared to other jobs. Jobs with a lower priority are executed first. | ✓ | ✓ | ✓ |
| Restrict Form options in Form Field Type to User permissions | formFieldShowOnlyAllowedForms: false | Enable this to only show forms the user or group has permissions to manage in the list of options for the Form Element Field Type (relating forms in Entries, etc). | ✓ | ✓ | ✓ |
| Remove Newlines from Textareas for Exporting | removeNewlines: true | Enable this to have newlines removed from Textarea fields in submissions when exporting. | ✓ | ✓ | ✓ |
| Use Option Labels when Exporting | exportLabels: true | Enable this to have fields with options use the submission's option labels instead of values when exporting. | ✓ | ✓ | ✓ |
| Use Field Handles for Headings when Exporting | exportHandlesAsNames: false | Enable this to use field handles as headings instead of field labels when exporting submissions. | ✓ | ✓ | ✓ |
| Fill Form Values from the GET Query String | fillWithGet: true | Enable this to be able to fill form field values from a GET query string in URI. To use this feature, make sure that the query in the URI matches the handle of the field(s) in the form, e.g. ?firstName=Bob&myRatingField=3. | ✓ | ✓ | ✓ |
| Enable Search Index Updating on New Submissions | updateSearchIndexes: true | Enable this to have Craft update search indexes whenever a new submission is created. | ✓ | ✓ | ✓ |
| Automatically Purge Submission Data | purgableSubmissionAgeInDays: '365' | Enable and specify the number of days after submissions have been submitted for Freeform to begin automatically purging. | ✕ | ✕ | ✓ |
Enabling the Purge Submissions feature and saving this settings page will result in purging feature beginning, and cannot be undone (it may not happen immediately, and may take a couple hours before the next process runs). This process will only run every hour, and only when Freeform is accessed on the front end in templates or in the control panel.
Form Behavior
Configure the front end form behavior.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Disable Submit Button on Form Submit | formSubmitDisable: true | Enable this to automatically disable the form's submit button when the user submits the form. This will prevent the form from double-submitting. | ✓ | ✓ | ✓ |
| Automatically Scroll to Form on Errors and Multipage forms | autoScrollToErrors: true | Enable this to have Freeform use JS to automatically scroll the page down to the form upon submit when there are errors or the form is continuing to the next page in multipage forms. | ✓ | ✓ | ✓ |
| Automatically Scroll to top of the Form on AJAX submit | autoScroll: true | Enable this when using AJAX to have Freeform use JS to automatically scroll the top of the form on submit. This is especially beneficial when you have longer forms and success/error messages at the top of the form become out of sight. | ✓ | ✓ | ✓ |
| Remember the Page Order in Multi-page forms | rememberPageSubmitOrder: true | When enabled, Freeform will take into account Conditional Rules page skipping when the user clicks the 'Previous' button on multi-page forms. | N/A | ✓ | ✓ |
| Use Queue for Email NotificationsNew in 5.4+ | useQueueForEmailNotifications: true | Use Craft's queue system to trigger emails. Enabling this will speed up submission processing for your users. This depends on either routine traffic to your Craft control panel or implementing a proper queue-processing method that doesn't rely on someone visiting your control panel. | ✓ | ✓ | ✓ |
| Use Queue for IntegrationsNew in 5.4+ | useQueueForIntegrations: true | Use Craft's queue system to trigger integrations (CRM and Email Marketing). Enabling this will speed up submission processing for your users. This depends on either routine traffic to your Craft control panel or implementing a proper queue-processing method that doesn't rely on someone visiting your control panel. | ✓ | ✓ | ✓ |
| Script Insert Location | scriptInsertLocation: footer | The location of where you want Freeform to insert it's scripts for form and field functionality (such as spam protection and advanced field types). More info Options are:
| ✓ | ✓ | ✓ |
| Script Insert TypeImproved in 5.3+ | scriptInsertType: files | Specify the way Freeform scripts are inserted. Options are:
| ✓ | ✓ | ✓ |
| Number of Days to Keep Saved Form Data (Save & Continue Later) | saveFormTtl: '14' | The number of days to store saved form progress in the database before clearing for Save & Continue Later feature. | N/A | ✓ | ✓ |
| Maximum Number of Saved Forms Per Session | saveFormSessionLimit: '5' | The maximum number of saved forms per session for Save & Continue Later feature. | N/A | ✓ | ✓ |
The Automatically Scroll to Form on Errors and Multipage forms feature can have its behavior can been manipulated with the Autoscroll Events.
Script Insert Location
The location of where you want Freeform to insert it's scripts for form and field functionality (such as spam protection and advanced field types).
- Page FooterRecommended
- Page HeaderNew in 5.0+
- Inside Form
- None (manually load the JS instead)
- If you choose this option, please be sure to manually load Freeform's JS with
/freeform/plugin.jsand CSS with/freeform/plugin.css(optional, as it's currently just for the Opinion field type handling) in your template(s). See Freeform JS plugin documentation for more information.
- If you choose this option, please be sure to manually load Freeform's JS with
Freeform Session ContextDeprecated in 5.0+
Choose the way form context is passed between form submits.
The PHP Sessions and Database Table options for the Freeform Session Context setting are deprecated and are planned to be removed in Freeform 6. Encrypted Payload continues to be the assumed and recommended approach, but can still be overrided to PHP Sessions or Database Table in project config.
Options are:
sessionContext: payload(default)sessionContext: sessionsessionContext: database
- As an encrypted payloadDefault/Recommended
- The key benefits are that it never stores anything anywhere, has no impact on the server, and can be cached out-of-the-box.
- Using PHP's sessions
- The key benefits are that it stores the context in memory and everything per session ID.
- The problems with this approach are that it expires eventually with no way to persist this for longer periods of time. It's also unreliable due to garbage collection on most servers which typically runs every 24 minutes by default.
- Using a database table
- The key benefits are that the context is stored in the database reliably for as long as you wish, offering more control if you have large forms that take a very long time to complete.
- The problems with this approach is that high traffic sites may run into performance issues as the database table fills up and attempts to clear regularly, etc.
Form BuilderImproved in 5.0+
Control Freeform's form builder experience.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Live Render HTML Markup | defaults: previewHtml: true | Live rendering HTML markup in field labels, option labels and HTML blocks inside the Form Builder interface can sometimes conflict with Freeform's display of the form preview inside the control panel. In cases like these, you'll need to disable this setting to prevent HTML from rendering automatically. | ✓ | ✓ | ✓ |
| Allow Twig to be enabled in HTML blocks | defaults: twigInHtml: true | A toggle will appear for each HTML block field inside the form builder, allowing the use of Twig code. | ✓ | ✓ | ✓ |
| Render HTML block Twig in Isolated Mode | defaults: twigIsolation: true | When enabled, only the Freeform 'form' and 'fields' variables will be available. If disabled, Craft's variables will be included as well. | ✓ | ✓ | ✓ |
| Include Freeform's Sample Formatting Templates | defaults: includeSampleTemplates: true | Allow users to select a sample formatting template included with Freeform for the form's Formatting Template setting. | ✓ | ✓ | ✓ |
| Form Builder Notifications tabNew in 5.0+ | defaults: notifications: ... | Set the default templates for each email notification type. Optionally lock values as well. | ✓ | ✓ | ✓ |
| Form Builder Settings tabNew in 5.0+ | defaults: settings: ... | Set the default values for settings. Optionally lock values as well. | ✓ | ✓ | ✓ |
Limited UsersProNew in 5.4+
- View the Limited Users documentation for more information about setting up and configuring.
This page and its settings all remain accessible when the Craft allowAdminChanges config setting is set to false.
Template ManagerImproved in 5.0+
The Template Manager settings page allows you to configure template directory paths and other settings for Formatting Templates, Email Notification Templates, and Success Templates.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
Formatting Templates
Formatting Templates are predefined templates that you can specify for forms to handle simplified rendering of the form on the front end. You can have as many as you wish, and customize them however you like.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Directory Path | formTemplateDirectory: _freeform/formatting/ | When using custom formatting templates for your forms, you'll need to specify where your Twig-based templates are stored. Provide a relative path to craft root to your custom form templates directory, e.g. freeform_formatting_templates. To add a starter example template, click the "Add a sample template" button, and then edit the template after. | ✓ | ✓ | ✓ |
Email Templates
Email Notification templates are available to be stored as files, in the database, or both. You can choose which one is best for your site. In order to send file-based email notifications, a directory path must be set for Freeform to manage these templates, as they are stored as Twig-based files. See Email Notifications documentation for more information about implementation.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Template Storage Type | emailTemplateStorageType: files_database | Choose whether you want to enable email notification templates stored as files, in the database, or have both options available. | ✓ | ✓ | ✓ |
| Default Email Template Creation Method | emailTemplateDefault: files | Select which storage method to use when creating new email notifications with 'Add New Template' option in the form builder. | ✓ | ✓ | ✓ |
| Default From Email for New TemplatesNew in 5.4+ | defaultFromEmail: 'email@mysite.net' | The default email address to be included in the 'From Email' setting of new email notification templates. | ✓ | ✓ | ✓ |
| Default From Name for New TemplatesNew in 5.4+ | defaultFromName: 'My Site' | The default name to be included in the 'From Email' setting of new email notification templates. | ✓ | ✓ | ✓ |
| Allow File-based Email Templates to be created inside the CP | allowFileTemplateEdit: true | Allowing users to generate template files from inside the CP can potentially cause issues with certain workflows. | ✓ | ✓ | ✓ |
| File Directory Path | emailTemplateDirectory: _freeform/emails/ | Provide a relative path to the Craft Templates folder where your email templates directory is. If you have not yet created the directory, please do that before filling in this setting. This allows you to use Twig template files for your email formatting and allows Freeform to locate these files when setting up notifications, e.g. _freeform_notifications. To add a starter example template, click the "Add a sample template" button, and then edit the template after. | ✓ | ✓ | ✓ |
If you wish to create advanced notification templates, please note that any additional template files (e.g. _layout.twig, _footer.html, etc) must NOT be stored inside of this directory, as Freeform expects that every file in here is a complete email notification template and will choke on any additional files.
Convert Database email templates to File email templates
This is a utility that allows you to migrate your existing database email templates over to file-based email templates (you can continue to edit these from the CP). The utility will also update all existing forms to use the new file version of the email template. If you wish to have Freeform clean up and remove the old database email templates after, check the checkbox as well.
Success Templates
Success templates are predefined templates that you can specify for your forms to display when a form has been successfully submitted. Instead of redirecting to a return URL or reloading the form, it'll display the contents of this template. You can have as many as you wish, and customize them however you like. To use these, be sure to select the Load Success Template option for the Success Behavior setting in the form builder for each form.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Directory Path | successTemplateDirectory: _freeform/success/ | When using custom formatting templates for your forms, you'll need to specify where your Twig-based templates are stored. Provide a relative path to craft root to your custom form templates directory, e.g. freeform_success. To add a starter example template, click the "Add a sample template" button, and then edit the template after. | ✓ | ✓ | ✓ |
Your success template might look something like this:
<div id="freeform-success">
<h3>Thank you!</h3>
<p>We have successfully received your submission.</p>
</div>
Things like form.id, form.handle and form.name are available for use here as well.
PDF TemplatesProNew in 5.7+
You can create an unlimited number of custom PDF's to be generated for email notifications. You are in full control to build beautiful HTML-based templates and dynamically pull in form and submission data. In the Email Notifications area, when editing an email notification template, you can then assign which PDF template(s) should be included with it.
The file name and PDF body may contain any of the Twig variables available in the body of email notification templates. Please see documentation for more information.
Each PDF template contains the following:
- Name
- Description
- File Name (the name of the PDF file when it's generated - can use Twig variables)
- PDF Body (uses HTML and can include Twig variables)
This page and its settings all remain accessible when the Craft allowAdminChanges config setting is set to false.
Statuses
This area allows you to manage and create new statuses for your forms. To set the default status, you can do so in the Form Builder defaults settings area.
This page and its settings all remain accessible when the Craft allowAdminChanges config setting is set to false.
Demo Templates
Allows you to install the Demo Templates to get Freeform up and running on the front end with just a couple clicks!
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
Spam Protection
For more information about Freeform's spam protection features, visit the Spam Protection documentation.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
| Setting | Project Config | Description | Express | Lite | Pro |
|---|---|---|---|---|---|
| Spam Protection Behavior | spamProtectionBehavior: simulate_successRenamed in 5.0+ | Select the behavior you'd like Freeform to take when it detects a submission as being spam: Simulate Success (recommended), Display Errors (for debugging). | ✓ | ✓ | ✓ |
| Bypass All Spam Checks for Logged in Users | bypassSpamCheckOnLoggedInUsers: false | When enabled, Freeform will not run any spam protection measures for logged in users. | ✓ | ✓ | ✓ |
| Use Spam Folder | spamFolderEnabled: true | When enabled, all submissions caught by the honeypot or blocked email addresses, keywords and IP addresses will be flagged as spam and stored in the database, but available to manage in a separate menu inside Freeform. When paired with a Captcha service and its Failure Behavior setting set to Send to Freeform Spam Folder, failed submissions will also end up in the Spam Folder. | ✓ | ✓ | ✓ |
| Automatically Purge Spam Submissions | purgableSpamAgeInDays: '14' | Enable and specify the number days that should pass after a spammy submission is received before Freeform automatically purges it. Enabling this and saving this settings page will begin the purging of submissions flagged as spam, and cannot be undone. | ✕ | ✓ | ✓ |
| Form Submission Throttling | submissionThrottlingCount: ''submissionThrottlingTimeFrame: m | Globally (affecting all users) prevent spam or attacks by limiting the number of times all forms can be submitted within a given timeframe. | ✓ | ✓ | ✓ |
| Minimum Submit Time | minimumSubmitTime: '' | The minimum amount of time (in seconds) that has to go by since loading the form for the user to be able to submit the form successfully. Otherwise the submission will be flagged as spam and the Spam Protection Behavior setting will take effect. | ✓ | ✓ | ✓ |
| Form Submit Expiration | formSubmitExpiration: '' | The maximum amount of time (in minutes) a user has to submit the form before the form expires and the Spam Protection Behavior setting will take effect. This still has to be less than the Craft CSRF token expiry and PHP Session limit set for your server. | ✓ | ✓ | ✓ |
Enabling the Spam Folder feature will not retroactively bring back any previously blocked spam submissions. Any submissions that have been blocked in the past (without Spam Folder setting on) are never recorded in the database.
Enabling the Purge Submissions feature and saving this settings page will result in purging feature beginning, and cannot be undone (it may not happen immediately, and may take a couple hours before the next process runs). This process will only run every hour, and only when Freeform is accessed on the front end in templates or in the control panel.
IntegrationsImproved in 5.0+
All integration pages and their settings remain accessible when the Craft allowAdminChanges config setting is set to false.
Email MarketingPro
The Email Marketing area allows you to manage your mailing list API integrations. Email Marketing integrations are set up here and are globally available to all forms, but are configured per form inside the form builder interface. To connect to an Email Marketing API, click the New Integration at the top right.
- View the Email Marketing Integration documentation for more information about setting up and configuring.
CRMPro
The CRM area allows you to manage your CRM (Customer Relationship Management) API integrations. CRM integrations are set up here and are globally available to all forms, but are configured per form inside the form builder interface. To connect to a CRM API, click the New Integration at the top right.
- View the CRM Integration documentation for more information about setting up and configuring.
PaymentsPro
This area allows you to configure and manage Stripe Payments for your forms. The Stripe Payments integration is set up here and are globally available to all forms, but are configured per form inside the form builder interface. To create a new Stripe payment setup, click the New Payment Integration at the top right.
- View the Payments API Integration documentation for more information about setting up and configuring.
CaptchasImproved in 5.0+
This area allows you to configure and manage Captcha integrations. Freeform currently supports several options of reCAPTCHA and hCaptcha.
- View the reCAPTCHA or hCaptcha integration documentation for more information about setting up and configuring.
WebhooksPro
This area allows you to configure and manage Slack, Zapier and generic Webhooks for your forms. The Webhooks integrations are set up and completely managed here. You specify which form(s) each Webhook applies to, etc. To create a new Webhook, click the New Webhook at the top right.
- View the Slack API Integration documentation for more information about setting up and configuring.
- View the Zapier API Integration documentation for more information about setting up and configuring.
OtherNew in 5.0+
This area allows you to configure and manage singleton integrations for your forms. Currently the following are available:
- Google Tag Manager
- Freeform Honeypot
- Freeform Javascript Test
- POST ForwardingPro
- Google SheetsProNew in 5.2+
Notices & Alerts
Freeform is committed to being the most robust and reliable form plugin for Craft CMS. Freeform has been carefully and meticulously developed and tested over many years and is in use across tens of thousands of websites. However, one other crutial piece of the puzzle in reliability is how your specific site and environment are performing. Because of this, Freeform includes an extensive error logging feature, email issue alerts, an Update Notices feature to alert you of important fixes and changes, and a weekly digest email to keep your finger on the pulse of your website.
This page and its settings all become inaccessible when the Craft allowAdminChanges config setting is set to false.
Check out the options below to learn more about each:
- Update Notices
- Email AlertsLitePro
- Weekly DigestLitePro
Error Log
In as many cases as possible, Freeform attempts to write errors and issues to its own error log. The file is physically located in the same place as the Craft logs (/storage/logs/freeform.log), but can be conveniently viewed inside the Error Log page inside Freeform Settings area (Freeform → Settings → Error Log). If there are no logged errors, the Error Log page will not show any errors, and you will likely not see the Freeform error log file.
This page remains accessible when the Craft allowAdminChanges config setting is set to false.
