React Google reCAPTCHA Wrapper

Common errors

• Error: reCAPTCHA has already been rendered in this element

  cause Attempting to render multiple reCAPTCHA widgets into the same DOM element or having conflicting reCAPTCHA instances without proper isolation.
  fix Ensure each `ReCAPTCHA` component renders into a unique DOM location. If embedding, consider using the `isolated` prop set to `true`.

• reCAPTCHA widget does not appear, or network errors in console (e.g., 'Failed to load resource')

  cause The `sitekey` prop is missing, incorrect, or not registered correctly with Google reCAPTCHA for the current domain. Alternatively, network issues, ad blockers, or Content Security Policy (CSP) restrictions might be preventing the script from loading.
  fix Double-check the `sitekey` value against your Google reCAPTCHA admin console and ensure the domain registration matches. Verify your browser console for network errors or CSP warnings, and ensure your CSP allows loading scripts from `www.google.com/recaptcha/api.js`.

• TypeError: Cannot read properties of null (reading 'getValue')

  cause Attempting to call `recaptchaRef.current.getValue()` or other instance methods before the component is fully mounted and the ref has been assigned.
  fix Ensure the ref is properly initialized and the component is mounted before accessing `recaptchaRef.current`. For functional components, use `useRef` and ensure the code accessing the ref runs after the component has rendered (e.g., within an `useEffect` or an event handler triggered after mount).

Warnings

• gotcha reCAPTCHA tokens obtained from the client-side `onChange` callback MUST be verified on a backend server using Google's reCAPTCHA API. Client-side validation alone is insecure and easily bypassed.
  Fix: Implement a server-side endpoint to receive the reCAPTCHA token and verify it with `https://www.google.com/recaptcha/api/siteverify` before processing any sensitive user action.
• gotcha reCAPTCHA tokens are typically one-time use. After a successful submission and backend verification, the reCAPTCHA widget must be manually reset using `recaptchaRef.current.reset()` to allow subsequent submissions.
  Fix: Call `recaptchaRef.current.reset()` in your component's logic after your backend successfully validates the token and completes the user action.
• gotcha For 'invisible' reCAPTCHA (`size="invisible"`), the challenge will not automatically trigger. You must programmatically invoke it using `recaptchaRef.current.execute()` or `recaptchaRef.current.executeAsync()`.
  Fix: Ensure you call `recaptchaRef.current.execute()` (typically on a form submission) when using `size="invisible"`. Integrate this with your form's submission handler.
• gotcha Using multiple `ReCAPTCHA` instances on the same page can lead to conflicts. If embedding the component within a plugin or widget, use the `isolated` prop.
  Fix: Set the `isolated={true}` prop on your `ReCAPTCHA` component if there's a possibility of other reCAPTCHA instances on the host page where your component is embedded.
• deprecated This library is specifically for Google reCAPTCHA v2. While v2 is still supported, Google has released reCAPTCHA v3 which operates differently (score-based, no user interaction). If you need v3, you will need a different library or custom integration.
  Fix: If reCAPTCHA v3 functionality is required, consider using a library specifically designed for v3 or integrating the v3 API directly.

Install

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

Imports

• ReCAPTCHA
  wrong:

  import { ReCAPTCHA } from 'react-google-recaptcha';

  correct:

  import ReCAPTCHA from 'react-google-recaptcha';

  ReCAPTCHA is exported as a default export.
• reCAPTCHA onChange event handler

  function onChange(value) { console.log('Captcha value:', value); }

  The onChange prop expects a function that receives the reCAPTCHA token as its first argument.
• reCAPTCHA ref methods (getValue, reset, execute)

  const recaptchaRef = React.createRef(); recaptchaRef.current.getValue();

  Access instance methods like getValue(), reset(), or execute() via a React ref to the ReCAPTCHA component.

Quickstart

Initializes and renders a visible Google reCAPTCHA v2 widget, logging the token on successful completion, expiration, or error. Requires a `root` element or will create one.

import React from 'react';
import ReactDOM from 'react-dom';
import ReCAPTCHA from 'react-google-recaptcha';

const RECAPTCHA_SITE_KEY = process.env.RECAPTCHA_SITE_KEY ?? '6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXwpTqiT'; // Example key

function App() {
  function onChange(value) {
    console.log('Captcha value:', value);
    // In a real application, send this 'value' (token) to your backend for verification.
  }

  function onExpired() {
    console.log('reCAPTCHA challenge expired.');
  }

  function onErrored(error) {
    console.error('reCAPTCHA challenge errored:', error);
  }

  return (
    <div>
      <h1>React Google reCAPTCHA Example</h1>
      <p>Please complete the reCAPTCHA to proceed.</p>
      <ReCAPTCHA
        sitekey={RECAPTCHA_SITE_KEY}
        onChange={onChange}
        onExpired={onExpired}
        onErrored={onErrored}
        theme="light"
        size="normal"
      />
      <p>Note: This sitekey is for demonstration only. Use your own client site key registered with Google reCAPTCHA.</p>
    </div>
  );
}

ReactDOM.render(<App />, document.getElementById('root') || document.createElement('div'));