> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crunchforms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# reCAPTCHA v3

> Advanced bot protection using reCAPTCHA v3

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](https://developers.google.com/recaptcha/docs/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][1] and [Guides][2] 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](/quickstart) (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][3] 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.

<Tip>
  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.
</Tip>

6. Accept the terms of service and click **Submit**.
7. You will be shown a **Site key** (public) and a **Secret key** (private).

<Tip>
  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.
</Tip>

***

## 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](https://crunchforms.com/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 <Icon icon="ellipsis-vertical" /> button and select **Edit Form Settings**.
3. Click on **Advanced Settings** 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.

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>

***

## Step 3: Embed reCAPTCHA v3 on your form page

Refer to Google’s [Client-side integration guide][2] for full details. In summary:

1. Load the reCAPTCHA v3 script (typically in `<head>`):

   ```html theme={null}
   <script src="https://www.google.com/recaptcha/api.js"></script>
   ```

2. Add a callback function to handle the token.

   ```html theme={null}
    <script>
        function onSubmit(token) {
            document.getElementById("demo-form").submit();
        }
    </script>
   ```

3. Add attributes to your html button.

   ```html theme={null}
    <button class="g-recaptcha" 
        data-sitekey="YOUR_SITE_KEY" 
        data-callback='onSubmit' 
        data-action='YOUR_ACTION'
    >
        Submit
    </button>
   ```

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>

***

## reCAPTCHA v3 Form Example

```html recaptcha-form.html theme={null}
<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>
```

<Tip>
  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.
</Tip>

***

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

You can [Programmatically invoke the challenge](https://developers.google.com/recaptcha/docs/v3#programmatically_invoke_the_challenge) to have more control over when reCAPTCHA runs. Below is an example using Next.JS.

### Next.JS reCAPTCHA v3 Example

```js RecaptchaForm.js theme={null}
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>
        </>
    );
}
```

<Note>
  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.
</Note>

***

## References

* [Google reCAPTCHA — Intro][1]
* [Google reCAPTCHA — v3 Integration guides][2]
* [Google reCAPTCHA Admin Console][3]

***

[1]: https://developers.google.com/recaptcha/intro "reCAPTCHA Intro"

[2]: https://developers.google.com/recaptcha/docs/v3 "reCAPTCHA v3 · Client and server integration"

[3]: https://www.google.com/recaptcha/admin "reCAPTCHA Admin Console"

***

## Next steps

Explore advanced configurations and features:

<CardGroup cols={2}>
  <Card title="Set up a Honeypot Field" icon="honey-pot" href="/advanced/honeypot">
    Get easy protection against simple bots using a hidden field
  </Card>

  <Card title="Set up Cloudflare Turnstile" icon="cloudflare" href="/advanced/turnstile">
    Advanced bot protection using Cloudflare Turnstile
  </Card>

  <Card title="Set up Google Recaptcha" icon="google" href="/advanced/recaptcha">
    Advanced bot protection using Google reCaptcha v3
  </Card>

  <Card title="Add additional email addresses" icon="at" href="/advanced/emails">
    Add and verify additional email addresses to receive form submission notifications
  </Card>
</CardGroup>

## Need Help?

<Card title="Get Support" icon="envelope" horizontal href="https://crunchforms.com/support">
  Send us a note
</Card>