hCaptcha Integration Improved in 5.0+
Freeform includes an integration for hCaptcha. Check out the options below.
Overview
All hCaptcha offerings will be automatically loaded and handled by Freeform (when enabled for the form). The hCaptcha Checkbox field will be automatically inserted above the Submit button(s).
Each hCaptcha 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 hCaptcha integrations supported by Freeform and how each of them work.
hCaptcha Checkbox LitePro
This is based off of reCAPTCHA and works very similarly. All users submitting your form must check off the hCaptcha checkbox, and in some cases, users will be presented the puzzle to solve to submit the form successfully.
hCaptcha Invisible LitePro
Most users will not even know it's automatically validating them, but like the hCaptcha Checkbox described above, some users will be presented a modal on the page with the puzzle to solve when they click the submit button.
Setup Instructions
WARNING
In order for this to work, the site you are connecting the integration to will need to be publicly accessible.
- Go to the hCaptcha admin site and log into your account.
- At the top left of the page, click on your profile icon and select Settings.
- On the next page, copy the value in the Secret Key field.
- If you don't already have an app created, click on the New Site icon button at the top right.
- Enter a name for it in the Add New Sitekey setting (optional).
- In the Domains section, enter in any domain(s) you plan on using the captcha for, e.g.
mysite.net. - Choose an option in the hCaptcha Behavior setting.
- Choose an option in the Passing Threshold setting.
- Scroll back to the top and click the Save button.
- On the next page, you'll be presented a Site Key for each app. Copy this key.
- If you have already created an app, the app name and Site Key will appear in the list of Sites.
- Copy the Site Key value.
- Leave this page open and open a new tab...
- Go to the Captchas section in Freeform Settings (Freeform → Settings → Captchas).
- Click the New Integration button at the top right.
- Select hCaptcha from the Service Provider select dropdown.
- Enter a name and handle for the integration. e.g.
My hCaptcha Integration. - Choose an hCaptcha version and type from the Captcha Type select dropdown.
- In the Site Key and Secret Key settings, paste in the Site Key and Secret Key values from the hCaptcha site.
- Complete the rest of the following optional fields (these will only be the default value when configuring the integration in the form builder later):
- Only load Captcha scripts once the user interacts with the form?
- Failure Behavior - set to
Display Error MessageorSend to Spam Folder.- Error Message - set a custom error message if using
Display Error Messagefailure behavior.
- Error Message - set a custom error message if using
- If using hCaptcha Checkbox, set the defaults for the following:
- Theme - set to
LightorDark. - Size - set to
NormalorCompact.
- Theme - set to
- Click the Save button.
To use this integration on your form(s), you'll need to configure each form individually.
- Visit the form inside the form builder.
- Click on the Integrations tab.
- Click on hCaptcha in the list of available integrations.
- On the right side of the page:
- Enable the integration.
- Adjust any of the settings as needed.
Behavior & Overrides
The following options are available for adjusting the behavior of hCaptcha 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,
}
}) }}
2
3
4
5
6
// Output (truncated for example)
...
<div class="custom-class another-class" data-test data-freeform-hcaptcha-container>
<div class="hcaptcha">
...
2
3
4
5