Freeform for Craft

5.x ✓ Latest

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

Plugin Store

Integrations

# reCAPTCHA Improved in 5.0+

# Overview

All reCAPTCHA offerings will be automatically loaded and handled by Freeform (when enabled for the form). The reCAPTCHA v2 Checkbox field will be automatically inserted above the Submit button(s).

Each reCAPTCHA integration is managed inside the Captchas area under Settings and then further configurable per form inside the form builder. Every integration is a little bit different, so please follow the detailed instructions for setting up the integration below.

# Supported Types

Below is a list of the reCAPTCHA integrations supported by Freeform and how each of them work.

# reCAPTCHA v2 Checkbox

All users submitting your form must check off the reCAPTCHA checkbox, and in some cases, users will be presented the puzzle to solve to submit the form successfully. This is available in all editions of Freeform.

# reCAPTCHA v2 Invisible

LitePro

Most users will not even know it's automatically validating them, but like the reCAPTCHA v2 Checkbox described above, some users will be presented a modal on the page with the puzzle to solve when they click the submit button.

# reCAPTCHA v3

LitePro

Users are never presented any puzzle to solve, etc. Instead, users are automatically validated by Google based on a score assigned to them. You have control over that score threshold inside Freeform settings. We suggest starting with something like 0.5 and see how that goes (where a 0.0 score means that it's almost certain a bot and a 1.0 score means it's a user). If the user does not pass this threshold, the submission will follow the behavior you set out for it in the settings (send to spam folder / reject it entirely / show an error to the user, etc). The user has no ability to validate themselves like in reCAPTCHA v2.

# Setup Instructions

# Behavior & Overrides

The following options are available for adjusting the behavior of reCAPTCHA and overriding at the template-level.

# Only load Captcha scripts once the user interacts with the form

If you'd like to have the associated Captcha scripts load only once a user begins filling out the form, enable the corresponding setting inside the Captchas settings page. If you'd like your forms to be ready to go at page load, disable this setting.

# Disabling Captchas

To disable Captchas per form at template level, add the disableCaptcha: true parameter to the Form query.

# Add Attributes to Wrapper New in 5.1+

You can add attributes to the main Captcha wrapper that is automatically inserted by Freeform.

{{ form.render({
    captchas: {
        class: ["custom-class", "another-class"],
        "data-test": true,
    }
}) }}

// Output (truncated for example)
...
<div class="custom-class another-class" data-test data-freeform-recaptcha-container>
    <div class="g-recaptcha">
...

# Load reCAPTCHA JS Manually

If you're loading an entire form via AJAX, you'll need to load the reCAPTCHA JS yourself, since it's considered insecure otherwise and the browser blocks it. You should add this script tag anywhere on your page, preferably the footer:

<script type="text/javascript" src="https://www.google.com/recaptcha/api.js?render=explicit"></script>

# Set the Action for reCAPTCHA v3

To set the action of reCAPTCHA v3, add recaptchaAction: "myaction" to your form.renderTag, like this:

{{ form.renderTag({ recaptchaAction: "myaction" }) }}

# Hiding the reCAPTCHA floating badge

reCAPTCHA v2 Invisible and reCAPTCHA v3 will automatically load a reCAPTCHA icon in the bottom right corner of your site containing the form. This is required by Google's terms of service. There are CSS workarounds if you wish to locate the icon to the left side of the browser page, etc.

If you'd like to hide the reCAPTCHA floating badge (bottom right for v2 Invisible and v3), you are allowed to do so as along as you provide reference to reCAPTCHA in the user flow. Quote and example from the Google reCAPTCHA docs:

You are allowed to hide the badge as long as you include the reCAPTCHA branding visibly in the user flow. Please include the following text:

This site is protected by reCAPTCHA and the Google
<a href="https://policies.google.com/privacy">Privacy Policy</a> and <a href="https://policies.google.com/terms">Terms of Service</a> apply.

1
2

Note: if you choose to hide the badge, please use:

.grecaptcha-badge { visibility: hidden; }

1