React Google reCAPTCHA v3 Integration

Common errors

• Error: reCAPTCHA has already been loaded on this page

  cause This error typically occurs if the reCAPTCHA script is loaded multiple times, either by having more than one `GoogleReCaptchaProvider` or by manually including the reCAPTCHA script alongside the library.
  fix Ensure there is only one `GoogleReCaptchaProvider` component in your application's React tree and remove any other `<script src="https://www.google.com/recaptcha/api.js..."></script>` tags from your HTML or component lifecycle methods.

• TypeError: Cannot read properties of undefined (reading 'executeRecaptcha')

  cause The `executeRecaptcha` function from `useGoogleReCaptcha` is `undefined` if the reCAPTCHA script has not finished loading, or if the hook is called outside the `GoogleReCaptchaProvider`'s context.
  fix Ensure the component calling `useGoogleReCaptcha` is a descendant of `GoogleReCaptchaProvider`. Always check `if (executeRecaptcha)` before attempting to call it. You might also want to display a loading state until `executeRecaptcha` becomes available.

• reCAPTCHA key is missing or invalid (often indicated by a console warning from Google reCAPTCHA itself)

  cause The `reCaptchaKey` prop was not provided to `GoogleReCaptchaProvider` or the provided key is incorrect/malformed.
  fix Obtain a valid reCAPTCHA v3 site key from the Google reCAPTCHA admin console and pass it as the `reCaptchaKey` prop to `GoogleReCaptchaProvider`. Verify that the key is correctly formatted and corresponds to your registered domain.

Warnings

• breaking In v1.7.0, the `nonce`, `async`, and `defer` props directly on `GoogleReCaptchaProvider` were grouped into a single `scriptProps` object. Existing direct usages will no longer function as expected.
  Fix: Migrate direct script-related props to the `scriptProps` object. For example, change `<GoogleReCaptchaProvider nonce='abc'>` to `<GoogleReCaptchaProvider scriptProps={{ nonce: 'abc' }}>`.
• gotcha When integrating Google reCAPTCHA Enterprise, you MUST create new site keys specifically for Enterprise and select 'Scoring' as the integration type. Standard reCAPTCHA v3 keys will not work with the `useEnterprise` prop enabled.
  Fix: Generate new reCAPTCHA Enterprise keys via the Google Cloud Console, ensure 'Scoring' integration is selected, and pass `useEnterprise={true}` to `GoogleReCaptchaProvider`.
• gotcha Placing multiple `GoogleReCaptchaProvider` instances in your application or placing it low in the component tree can lead to performance issues, unnecessary script reloads, or reCAPTCHA conflicts.
  Fix: Ensure `GoogleReCaptchaProvider` is placed as high as possible in your React component tree, typically at the root of your application, to ensure a single, consistent reCAPTCHA instance.
• deprecated The `withGoogleReCaptcha` Higher-Order Component (HOC) is primarily for class components. While still supported, the `useGoogleReCaptcha` hook is the recommended and more idiomatic approach for functional components. The HOC may be considered for removal in future major versions.
  Fix: For new development and functional components, prefer using the `useGoogleReCaptcha` hook. Refactor existing class components to use the hook if migrating to functional components.

Install

• npm install react-google-recaptcha-v3 npm
• yarn add react-google-recaptcha-v3 yarn
• pnpm add react-google-recaptcha-v3 pnpm

Imports

• GoogleReCaptchaProvider
  wrong:

  const { GoogleReCaptchaProvider } = require('react-google-recaptcha-v3');

  correct:

  import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

  This component should wrap your application or relevant parts to provide reCAPTCHA context. Place it high in the component tree to avoid reloads.
• useGoogleReCaptcha
  wrong:

  import useGoogleReCaptcha from 'react-google-recaptcha-v3/dist/useGoogleReCaptcha';

  correct:

  import { useGoogleReCaptcha } from 'react-google-recaptcha-v3';

  The recommended hook for functional components to programmatically execute reCAPTCHA validation. The `executeRecaptcha` function returned by the hook may be `undefined` until the script is loaded.
• withGoogleReCaptcha
  wrong:

  import WithGoogleReCaptcha from 'react-google-recaptcha-v3/withGoogleReCaptcha';

  correct:

  import { withGoogleReCaptcha } from 'react-google-recaptcha-v3';

  A higher-order component (HOC) primarily for class components, injecting reCAPTCHA functionality via props. The documentation recommends `useGoogleReCaptcha` for functional components.

Quickstart

This quickstart demonstrates how to set up `GoogleReCaptchaProvider` and use the `useGoogleReCaptcha` hook to execute reCAPTCHA v3 verification upon form submission. It shows handling of loading states and the retrieved token, and highlights the necessity of providing a site key.

import React, { useState, useCallback, useEffect } from 'react';
import { GoogleReCaptchaProvider, useGoogleReCaptcha } from 'react-google-recaptcha-v3';

const RECAPTCHA_SITE_KEY = process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY ?? 'YOUR_SITE_KEY';

const RecaptchaForm = () => {
  const { executeRecaptcha } = useGoogleReCaptcha();
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleReCaptchaVerify = useCallback(async () => {
    setLoading(true);
    setError(null);
    if (!executeRecaptcha) {
      setError('reCAPTCHA not loaded yet!');
      setLoading(false);
      return;
    }

    try {
      const result = await executeRecaptcha('form_submission');
      setToken(result);
      console.log('reCAPTCHA token:', result);
      // In a real application, send this token to your backend for verification
    } catch (e) {
      console.error('reCAPTCHA execution failed:', e);
      setError('Failed to get reCAPTCHA token.');
    } finally {
      setLoading(false);
    }
  }, [executeRecaptcha]);

  useEffect(() => {
    // Optionally execute reCAPTCHA on component mount or a specific event
    // handleReCaptchaVerify(); 
  }, [handleReCaptchaVerify]);

  return (
    <div>
      <h1>Contact Us</h1>
      <form onSubmit={(e) => { e.preventDefault(); handleReCaptchaVerify(); }}>
        {/* Your form fields here */}
        <p>This form is protected by reCAPTCHA.</p>
        <button type="submit" disabled={loading}>
          {loading ? 'Verifying...' : 'Submit Form'}
        </button>
        {token && <p>Token received: {token.substring(0, 15)}...</p>}
        {error && <p style={{ color: 'red' }}>Error: {error}</p>}
      </form>
    </div>
  );
};

export default function App() {
  if (!RECAPTCHA_SITE_KEY || RECAPTCHA_SITE_KEY === 'YOUR_SITE_KEY') {
    console.error('Please provide a reCAPTCHA site key via NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable or directly in the code.');
    return <div>Error: reCAPTCHA site key is missing.</div>;
  }
  return (
    <GoogleReCaptchaProvider reCaptchaKey={RECAPTCHA_SITE_KEY} scriptProps={{ defer: true, async: true }}>
      <RecaptchaForm />
    </GoogleReCaptchaProvider>
  );
}