Skip to main content
Add anti-bot protection to your forms using reCAPTCHA v3. Crunchforms handles server-side token validation out of the box and will reject submissions that contain invalid tokens or that score below the threshold you set.

​
Why use reCAPTCHA v3 with Crunchforms

  • reCAPTCHA v3 provides a frictionless, score-based spam protection system from Google that does not interrupt users with challenges.
  • Because Crunchforms already handles server-side validation of the reCAPTCHA token and score, you only need to execute reCAPTCHA on the front end and configure your keys and score threshold.
  • Once configured, any submission via Crunchforms that fails token validation or scores below your configured threshold will be rejected automatically — minimal extra code required.

​
Prerequisites

Before you start:
  • Read through Google’s reCAPTCHA v3 Intro and Guides to understand how it works and how scoring is used.
  • You must have a Google account and access to the reCAPTCHA Admin Console.
  • You must have a Crunchforms form set up (you already have a form-endpoint configured).
  • Access to edit the HTML (or embed) of your form page to add the reCAPTCHA script and token handling.

​
Step 1: Create your reCAPTCHA v3 keys (in Google Admin Console)

Follow Google’s reCAPTCHA documentation for this part:
  1. Go to the reCAPTCHA Admin Console and sign in.
  2. Click + Create (or + button) to register a new site.
  3. Provide a descriptive Label for your site.
  4. Select reCAPTCHA v3 as the type.
  5. Add the domain(s) where your forms will be hosted.
If you need to use recaptcha during local testing, you may need to add localhost as a domain temporarily, or set up a keys specifically for testing.
  1. Accept the terms of service and click Submit.
  2. You will be shown a Site key (public) and a Secret key (private).
Keep your secret key secure. Don’t expose it in client-side code on your website. The Secret key will be added to your form configuration in Crunchforms and will be used to validate submitted tokens and check scores.

​
Step 2: Configure Crunchforms to use your reCAPTCHA v3 key

In your Crunchforms dashboard, edit the form settings for the form you want to protect:
  1. Navigate to your dashboard
  2. Edit the form settings by selecting Edit Form Settings from the action dropdown next to the form you would like to edit, or from the submission view, click the button and select Edit Form Settings.
  3. Click on Advanced Setttings to expand the advanced options.
  4. Scroll to the bottom to find the reCAPTCHA v3 configuration section.
  5. Turn on Use reCAPTCHA v3
  6. Enter your Secret Key from Step 1 in the reCAPTCHA v3 Secret Key field.
  7. Configure your desired minimum Threshold Score (0.0 - 1.0). Submissions scoring below this value will be rejected.
  8. Set your action name. This will need to match the action name you configure as your reCAPTCHA action in your website. i.e. submitForm.
  9. Save your changes.
If you have reCAPTCHA enabled and valid values in the reCAPTCHA fields, Crunchforms will expect a token in your submissions and will attempt to validate it and check the score. If validation fails, or the score is below your configured threshold, the submission will be rejected. Clear this configuration if you do not want to enforce reCAPTCHA v3 for this form.
With Crunchforms, you do not need to write any custom server-side code for token validation — Crunchforms will automatically validate the token with Google’s reCAPTCHA API and reject invalid/expired tokens or low-score requests. Tokens must be submitted along with the form data under the g-recaptcha-response field name (the default for reCAPTCHA) or recaptchaToken field name.

​
Step 3: Embed reCAPTCHA v3 on your form page

Refer to Google’s Client-side integration guide for full details. In summary:
  1. Load the reCAPTCHA v3 script (typically in <head>): 
    <script src="https://www.google.com/recaptcha/api.js"></script>
  2. Add a callback function to handle the token. 
     <script>
     function onSubmit(token) {
         document.getElementById("demo-form").submit();
     }
 </script>
  3. Add attributes to your html button. 
     <button class="g-recaptcha" 
     data-sitekey="YOUR_SITE_KEY" 
     data-callback='onSubmit' 
     data-action='YOUR_ACTION'
 >
     Submit
 </button>
Replace "YOUR_SITE_KEY" with the Site key from your reCAPTCHA v3 configuration and "YOUR_ACTION" with the acton you configured on the Crunchforms Dashboard. This will be used to validate your token’s action matches the action configured.
Because Crunchforms handles the server validation step and score checking, you just need to ensure the token is generated on the client side and included in your submission under g-recaptcha-response. Crunchforms will validate the token with Google, inspect the score and action, and only accept submissions that meet or exceed your configured threshold.

​
reCAPTCHA v3 Form Example

recaptcha-form.html
<html>
	<head>
		<script src="https://www.google.com/recaptcha/api.js"></script>
		<script>
			function onSubmit(token) {
				document.getElementById("demo-form").submit();
			}
		</script>
	</head>
	<body>
		<form 
			id="demo-form"
			action="https://crunchforms.com/form/{formID}" 
			method="post"
		> 
			<label for="email">Please Enter Your Email</label> 
			<input name="email" type="email" id="email" /> 
			<button 
				class="g-recaptcha" 
				data-sitekey="reCAPTCHA_site_key" 
				data-callback='onSubmit' 
				data-action='submit'
			>
				Submit
			</button>
		</form>
	</body>
</html>
When this function is triggered by a reCAPTCHA element (e.g., a button with class="g-recaptcha", data-callback="onSubmit"), the reCAPTCHA library automatically adds the g-recaptcha-response parameter containing the token to the form data when the form is submitted.

​
Use with Single Page Applications, React, and Next.js

You can Programmatically invoke the challenge to have more control over when reCAPTCHA runs. Below is an example using Next.JS.

​
Next.JS reCAPTCHA v3 Example

RecaptchaForm.js
import Script from "next/script";

export default function RecaptchaForm(props) {

    function onSubmit(event) {
        event.preventDefault()
        const data = new FormData(event.target)

        window.grecaptcha.ready(function() {
            window.grecaptcha.execute("YOUR_SITE_KEY", {action: 'YOUR_ACTION'}).then(function(token) {
                // Add your logic to submit to your backend server here.
                data.append('recaptchaToken', token);
                submit(data)
            });
        });
    };

    return (
        <>
            <Script src={"https://www.google.com/recaptcha/api.js?render="+"YOUR_SITE_KEY"} />

            <form onSubmit={onSubmit} > 
                <label for="email">Please Enter Your Email</label> 
                <input name="email" type="email" id="email" /> 
                <button type="submit">
                    Submit
                </button>
            </form>
        </>
    );
}
You must ensure that the token provided by reCAPTCHA is ultimately included in the form submission under the g-recaptcha-response or recaptchaToken field name so that Crunchforms can validate it server-side.

​
References

​
Next steps

Explore advanced configurations and features:

Set up a Honeypot Field

Get easy protection agains simple bots using a hidden field

Set up Cloudflare Turnstile

Advanced bot protectionion using Cloudflare Turnstile

Set up Google Recaptcha

Advanced bot protectionion using Google reCaptcha v3

Add additional email addresses

Add and verify additional email addresses to receive form submission notifications

​
Need Help?

Get Support

Send us a note