Skip to main content

Cloudflare Turnstile Integration
LitePro
New in 5.6.5+

Freeform includes an integration for Cloudflare Turnstile. Check out the options below.

​Overview

The Cloudflare Turnstile widget will be automatically loaded and handled by Freeform (when enabled for the form). The banner or checkbox field will be automatically inserted above the Submit button(s).

​Managed

Cloudflare will use information from the visitor to decide if an interactive challenge should be used. If we do show an interaction, the user will be prompted to check a box (no images or text to decipher).

​Non-interactive

A purely non-interactive challenge. Users will see a widget with a loading bar while the browser challenge is run.

​Invisible

Invisible challenge that does not require interaction.

​Setup Instructions

1

​Set up Widget on Cloudflare site

  • Go to the Cloudflare Dashboard site and log into your account.
  • Click on Turnstile in the navigation menu.
  • If you don't already have a Turnstile widget created, click on the Add Widget button.
    • Enter a name for it in the Widget name setting.
    • In the Domains section, enter in any domain(s) you plan on using the captcha for, e.g. mysite.net.
    • Choose a type in the Widget Mode setting.
    • Click the Create button.
    • On the next page, you'll be presented a Site Key and Secret Key. Copy both of these.
2

​Set up Integration on your site

  • Go to the Captchas section in Freeform Settings (Freeform → Settings → Captchas).
  • Click the New Integration button at the top right.
  • Select Turnstile from the Service Provider select dropdown.
  • Enter a name and handle for the integration. e.g. My Turnstile Integration.
  • In the Site Key and Secret Key settings, paste in the Site Key and Secret Key values from the Cloudflare site.
3

​Additional Configuration

  • 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 Message or Send to Spam Folder.
      • Error Message - set a custom error message if using Display Error Message failure behavior.
    • Theme - set to Auto, Light or Dark.
    • Size - set to Normal (300x65px), Flexible (100%x65px) or Compact (150x140px).
    • Action - the action to use when validating the Captcha, e.g. submit.
    • Locale - the locale to use for the Captcha as the language ID, e.g. en, de, etc. If left blank, the locale will be auto-detected.
  • Click the Save button.
4

​Configure the Form

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 Turnstile in the list of available integrations.
  • On the right side of the page:
    • Enable the integration.
    • Adjust any of the settings as needed.
Finished!

​Behavior & Overrides

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

​Disabling Captchas

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

​Manual PlacementNew in 5.7+

If you need full control over the placement of the visible Turnstile captcha, please see the Captcha Placement guide.

​Add Attributes to WrapperNew 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,
    }
}) }}
Page Feedback