Freeform Freeform for Craft

Installing & Updating

Updating from Freeform 4.x


Due to the nature of this update we recommend anyone upgrading from Freeform 4.x to do so carefully in a development environment and follow the special instructions below.

Key Changes

The Freeform 5.0 update is a major overhaul to the structure, templating, and form builder organization. There are many breaking changes that will allow us to continue to improve Freeform in the future. Please note all key changes below:


Freeform 4.x

Freeform 5.x

Required Action

Field ManagementAffects: All
Fields were global across all forms, making reusing them easier (though had its many downfalls) Fields are created as needed, and are purely per form. Fields can be cloned or reused, however, as the form builder allows you to pull in fields from other forms or save common fields as Favorites. No action is necessary. The migration from Freeform 4 will respect the new architecture and recreate all fields into each form. If you do have a need for a set of common fields, e.g. First Name, Last Name, Email Address, you could open up a form in the form builder and save any number of these as a Favorite.
Field Type NamingAffects: All
Multi-word field handles were named with underscores, e.g. opinion_scale. Multi-word field handles are named with hyphens, e.g. opinion-scale and some have been renamed for clarity. If you are referencing any of these field types in your template code, update the field type handles of cc_details, confirmation, file_drag_and_drop, multiple_select, opinion_scale, and rich_text to stripe, confirm, file-dnd, multiple-select, opinion-scale, and rich-text, respectively.
Field Type NamingAffects: All
Select dropdown fields, checkbox groups, and radio groups were referred to as Select, Checkbox Group, and Radio Group (and select, checkbox_group, and radio_group inside templates), respectively. To be more intuitive to all users (and consistent with Craft), select dropdown fields, checkbox groups, and radio groups are now referred to as Dropdown, Checkboxes, and Radios (and dropdown, checkboxes, and radios inside templates), respectively. All Select, Checkbox Group, and Radio Group fields will be migrated to Freeform 5 using the new field type names. If applicable, adjust any templating markup to use dropdown, checkboxes, and radios.
Email NotificationsAffects: All
Configuring email notifications for Email fields was done in the property editor for the field. Configuring email notifications for Email fields is now done in the Notifications tab for each field. This allows you to see an overview of all notifications configured for the form. No action is necessary. The migration from Freeform 4 will create an Email field in the form layout and configure a notification for it inside the Notifications tab.
Submit ButtonsAffects: All
Submit (and Back, Save & Continue Later) buttons were available as special fields to be inserted into the form layout. Submit, Back, and Save & Continue Later buttons are now automatically inserted into the form layout (as necessary). However, there are manual options for greater control over customization as well. In order to control the classes and styles of buttons in the form, please use the new buttons approach at template-level, specify attributes for them inside the form builder, or use the manual submit buttons approach. Please see the Submit Button Customization documentation for more information.
Freeform Honeypot / Javascript TestAffects: Most
The Freeform Honeypot offers basic protection against forms. The Javascript Test enhances the Honeypot test by performing an action to it that requires javascript to be enabled in the browser. The Freeform Honeypot and Javascript Test features have been decoupled, overhauled, and set up as integrations. They can now be enabled/disabled and configured per form. The Javascript Test is now a simpler approach that will streamline use with caching or headless implementations. If you wish to use/continue to use the Honeypot and/or Javascript Test feature, please enable them inside the Integrations area of the Freeform settings. If you're using these features with caching, please review the Caching documentation to update your template code as necessary. If you're using a headless approach, please review the GraphQL documentation to update as necessary.
IntegrationsAffects: Most
Integrations were handled in a variety of ways and the experience was inconsistent. The architecture has changed, and integrations are all set up similarly and can be fine tuned better per form inside the form builder. This approach also allows for easy toggling on/off integrations, so it will be easier to have different ones configured per environment, e.g. Production, Development. Many CRM and Email Marketing integrations now use OAuth for better security as well. The migration from Freeform 4 will NOT carry forward any integrations. They will need to be set up again. This includes CRM, Email Marketing, Elements (Element Connections), Stripe Payments, Webhooks, Captchas, etc.
Sample TemplatesAffects: Most
A wide variety of sample formatting templates were included with Freeform to easily get started with displaying forms. Freeform 5 continues to offer a wide variety of sample formatting templates and they have been revised and improved. Not all sample formatting templates were carried over to Freeform 5. The Bootstrap 3, Bootstrap 4, Bootstrap 5 Multipage All Fields and Tailwind 1 formatting templates have been removed. A basic Multipage All Fields formatting template now replaces the Bootstrap 5 Multipage All Fields template. If you're using any of the sample formatting templates, the migration will attempt to update the formatting template to the closest available one, e.g. Tailwind 1Tailwind 3, Bootstrap 4Bootstrap 5, etc. All sample formatting templates have been revised, however, so you should review how each one displays within your site and adjust CSS, etc as necessary.
Dynamic RecipientsAffects: Most
Forms could allow users to select which recipient(s) the form submission should be emailed to using the Dynamic Recipients field type. Forms can allow users to select which recipient(s) the form submission should be emailed to using any regular option-based field type that is configured as a User Select field inside the form builder. This allows for much greater power and flexibility, and allows values to be stored correctly in the database. The migration from Freeform 4 will transition any Dynamic Recipient fields to the proper field type they were emulating before. E.g. Dynamic Recipients displayed as a Select dropdown will become a Dropdown field in Freeform 5, and then configured as a User Select notification type inside the Notifications tab of the form builder.
Captcha IntegrationsAffects: Most
When using reCAPTCHA v2 Checkbox and hCaptcha Checkbox, a special field became available to insert into your form layout in the form builder. When using any Captcha, including reCAPTCHA v2 Checkbox and hCaptcha Checkbox, Freeform will automatically insert them into the form before the Submit button. All Captcha integrations need to be set up again in Freeform 5. If using reCAPTCHA v2 Checkbox or hCaptcha Checkbox, keep in mind that these are automatically handled by Freeform now, once enabled inside the Integrations section of the form builder.
Template Directory PathsAffects: Most
Configuring template directories used to be done in one of three settings pages: Formatting Templates, Email Templates and Success Templates. The Formatting Templates, Email Templates and Success Templates settings pages have now been combined into one unified Template Manager settings page No action is necessary.
Email Marketing IntegrationsAffects: Most
Email Marketing opt-in fields were done with a special field type that did not store any data. Email Marketing integrations now let you set the target opt-in field. This makes templating cleaner and also stores a record of the data (if they opted in, etc). All email marketing integrations need to be set up again in Freeform 5. Please keep in mind that when configuring the form inside the form builder, you will need to add a regular Checkbox (or other) field into the form layout and set up the integration to target that field.
Form/Field AttributesAffects: Most
Form and field attributes were controlled at template-level with the following parameters: inputClass, submitClass, rowClass, columnClass, labelClass, errorClass, instructionsClass, class, id, name, method, action and useRequiredAttribute. Form and field attributes are now controlled with the Template Overrides feature, allowing for powerful and flexible fine tuning of attributes and default values, labels, etc. Please update any of these attribute control parameters to use the new Template Overrides approach instead. More info...
Field Instructions PositioningAffects: Some
To display the field instructions below the field input instead of below the field label when using field.render, you could use the instructionsBelowField parameter. Freeform 5 no longer includes this parameter. Using the updated formatting template approach and the Template Overrides feature, you can simply use the individual field render methods instead (field.renderLabel, field.renderInput, field.renderInstructions, field.renderErrors). If your site relies on this feature, please review your custom formatting templates and update as necessary.
StripeAffects: Some
The Stripe integration uses the Payment Intents approach and was limited with what it could do. Freeform 5 uses the newer Stripe Payment Element approach, which includes support for over 40+ payment methods including Stripe Link, Apple Pay, Google Pay, PayPal (within Europe), Bank payments, deferred payments and many other options. We also added the ability to include more than one Stripe payment element field in a single form. When used with conditional rules, you can show/hide one Stripe element at a time (e.g. use a dropdown field to allow the user to choose between one-time or recurring payments). The migration from Freeform 4 will NOT carry forward the Stripe integration or any field mappings, etc. They will need to be set up and reconfigured again.
Checked OptionsAffects: Some
Checking if a field option was checked could be done with option.checked. This is now done by comparing option.value to field.value in your template. The option.checked property has been removed. Any use of render on fields should handle this automatically, but if you're manually generating forms, please replace any instances of option.checked with a compare check on option.value to field.value.
Success/Error BannersAffects: Some
The defaults for errorClassBanner, errorClassList, errorClassField and successClassBanner plugin options for JS overrides were ff-form-errors, ff-errors, ff-has-errors and ff-form-success The defaults for errorClassBanner, errorClassList, errorClassField and successClassBanner plugin options for JS overrides are now freeform-form-errors, freeform-errors, freeform-has-errors and freeform-form-success If you're using AJAX on any form and overriding any of these, please change ff- to freeform- as necessary.
Override Field ValuesAffects: Some
Field values could be overrided/selected at template-level with the overrideValues parameter. Field values can be overrided/selected at template-level with the value parameter in the new Template Overrides feature. If using this feature, please update any instances of overrideValues in your Form queries to use this new approach. More info...
Option Values/LabelsAffects: Few
To display submission data on the front end or in email notification templates, you could use value or valueAsString. However, if you're displaying submission data from a field such as Dropdown or Checkboxes, you did not have control over whether the option value or label was used. To access field option labels, you can use the new labels and labelsAsString methods. No action is necessary. However, if you wish to use option Labels instead of Values, adjust any instances of value and valueAsString to labels and labelsAsString as necessary.
Surveys & PollsAffects: Few
Freeform 3 & 4 offer an add-on purchase of a Surveys & Polls form type plugin to extend reporting functionality. This functionality is now included in the Pro edition of Freeform and is no longer a separate plugin.
  1. Before upgrading to Freeform 5, uninstall the Freeform Surveys & Polls plugin.
  2. Update to Freeform 5 and ensure you're on the Pro edition.
  3. Visit the Surveys & Polls settings area to set the defaults for reports.
  4. For each applicable form, change the Form Type setting in the form builder from Regular to Surveys & Polls.
Disabling CaptchasAffects: Few
Captchas could be disabled at template-level by using the disableRecaptcha template parameter. Captchas can be disabled at template-level by using the disableCaptcha template parameter. The disableRecaptcha template parameter has been removed. Please use disableCaptcha instead.
File Drag & Drop CSSAffects: Few
CSS overrides for File Drag & Drop fields started with freeform-file-drag-and-drop. CSS overrides for File Drag & Drop fields are now shorted to start with freeform-file-dnd. If using File Drag & Drop fields and overriding CSS styles, please update all references of freeform-file-drag-and-drop to freeform-file-dnd.
Duplicate SubmissionsAffects: Few
To prevent duplicate submissions, a Limit Form Submission Rate setting was available in the form builder per form. That setting has now been renamed to Duplicate Check and all available options have been revised and renamed for clarity as well. No action is necessary. The migration from Freeform 4 will attempt to update this form setting to the new option name or closest available option.
Templating NamespaceAffects: Few
When making Freeform queries, you would need to use craft.freeform.whatever. Freeform 5 includes a global freeform variable so that queries can be done shorthand as freeform.whatever instead. No action is necessary. Both craft.freeform.whatever and freeform.whatever will work. You can use whichever you like.
Disable/Suppress Emails/IntegrationsAffects: Few
Use the suppress parameter on your form query to suppress email notifications and integrations when editing submissions on the front end. This parameter has been renamed to disable, and some of the option names for it have changed to fit the updated architecture and naming. It also now includes the ability to disable spam protection features. If using this feature, please update the parameter to disable and its options: dynamicRecipients, submitterNotifications, and connections parameter names to userSelectNotifications, emailFieldNotifications, and elements, respectively. Additional options are conditionalNotifications, captchas, honeypot, and javascriptTest. If you're using the disableCaptcha and disableHoneypot parameters, please be sure to move that to the new approach within the disable parameter.
GraphQLAffects: Few
GraphQL field names and approaches. Some field names and approaches in GraphQL have been removed or replaced with different architecture. If using the POST Forwarding or Google Tag Manager features, please see the new Integration approaches. If applying attributes for inputs, labels, errors and instructions, please use FreeformAttributesInterface instead.
Form SessionsAffects: Few
Site admins have the option to choose between the following form session contexts: Encrypted Payload, PHP Sessions, and Database Tables The Freeform Session Context setting has been removed. Encrypted Payload continues to be the assumed and recommended approach, but can still be overrided to PHP Sessions or Database Table deprecated options in project config. No action is necessary for the vast majority of sites. If your site currently uses PHP Sessions or Database Table, it'll continue to work throughout Freeform 5.x. However, it will be removed for Freeform 6+, so please consider switching to Encrypted Payload instead.
HTML/Rich Text FieldsAffects: Few
When manually rendering forms, field.value was used to output the contents of these field types. When manually rendering forms, field.renderInput is now used to output the contents of these field types. If your site is manually loading any HTML or Rich Text field types in your templates, please ensure that you are using field.render or field.renderInput to display its contents.

Updating from 3.x

While updating from Freeform 3.x directly to 5.x is possible, we strongly recommend the following additional steps to help the process go smoother...


Be sure to back up your site files and database before proceeding.

Updating from 4.x


Be sure to back up your site files and database before proceeding.

  "require": {
      "craftcms/cms": "^5.0.0",
      "vlucas/phpdotenv": "^5.4.0",
-     "solspace/craft-freeform": "^4.0.0",
+     "solspace/craft-freeform": "^5.0.0",
      "solspace/craft-calendar": "^5.0.0"
  • Get the latest 5.x package of Freeform by running the following command:

    php craft update freeform
    • To get a specific version, run the following command:
      php craft update freeform:5.3.0
  • Perform the migration one of two ways:

    • In your CLI, run one of the following commands (all plugins including Craft, or just Freeform): Recommended

      php craft migrate/all


      php craft migrate --plugin=freeform

      The CLI will then present something like this:

      [username@Computer site.test % php craft migrate --plugin=freeform 
      Checking for pending Freeform migrations ...
      Total 29 new migrations to be applied:
      Apply the above migrations? (yes|no) [no]:


    • Proceed to the Craft control panel and click the Finish Updates button when it shows.


      Sites with a larger number of forms, fields, and submission data could experience issues doing it this way, which is why we strongly recommend the CLI approach instead.

  • Be sure to apply any changes noted in the key features/changes table above.
  • Carefully review and update all Freeform settings, submission data and forms in the form builder.
  • Also be sure to review and update your templates and formatting templates (if you have any custom ones) and ensure that everything works correctly and any necessary updates are made.
  • If you plan to use the demo templates to review/text/experiment, please reinstall them if you already installed then in an earlier version of Freeform.