README.md

React Google Recaptcha V3

React library for integrating Google ReCaptcha V3 to your App.

Install

npm install react-google-recaptcha-v3

Usage

Provide Recaptcha Key

To use react-google-recaptcha-v3, you need to create a recaptcha key for your domain, you can get one from here.

Enterprise

When you enable to use the enterprise version, you must create new keys. These keys will replace any Site Keys you created in reCAPTCHA. Check the migration guide.

To work properly, you must select the Integration type to be Scoring since is equivalent to the reCAPTCHA v3.

The complete documentation to the enterprise version you can see here.

Components

GoogleReCaptchaProvider

react-google-recaptcha-v3 provides a GoogleReCaptchaProvider provider component that should be used to wrap around your components.

GoogleReCaptchaProvider's responsibility is to load the necessary reCaptcha script and provide access to reCaptcha to the rest of your application.

You can customize the injected script tag with the scriptProps prop. This prop allows you to add async, defer, nonce attributes to the script tag. You can also control whether the injected script will be added to the document body or head with appendTo attribute. Example can be found belows. The scriptProps and its attributes are all optional.

It also provides an optional prop language to support different languages that is supported by Google Recaptcha. https://developers.google.com/recaptcha/docs/language

The provider also provide the prop useRecaptchaNet to load script from recaptcha.net: https://developers.google.com/recaptcha/docs/faq#can-i-use-recaptcha-globally

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

ReactDom.render(
  <GoogleReCaptchaProvider
    reCaptchaKey="[Your recaptcha key]"
    language="[optional_language]"
    useRecaptchaNet="[optional_boolean_value]"
    useEnterprise="[optional_boolean_value]"
    scriptProps={{
      async: false, // optional, default to false,
      defer: false, // optional, default to false
      appendTo: "head", // optional, default to "head", can be "head" or "body",
      nonce: undefined // optional, default undefined
    }}
  >
    <YourApp />
  </GoogleReCaptchaProvider>,
  document.getElementById('app')
);

There are three ways to trigger the recaptcha validation: using the GoogleReCaptcha component, wrapping your component with the HOC withGoogleReCaptcha, or using the custom hook useGoogleReCaptcha.

GoogleReCaptcha

GoogleRecaptcha is a react component that can be used in your app to trigger the validation. It provides a prop onVerify, which will be called once the verify is done successfully.

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

ReactDom.render(
  <GoogleReCaptchaProvider reCaptchaKey="[Your recaptcha key]">
    <GoogleReCaptcha onVerify={handleVerify} />
  </GoogleReCaptchaProvider>,
  document.getElementById('app')
);

// IMPORTANT NOTES: The `GoogleReCaptcha` component is a wrapper around `useGoogleRecaptcha` hook and use `useEffect` to run the verification.
// It's important that you understand how React hooks work to use it properly.
// Avoid using inline function for the `onVerify` props as it can possibly cause the verify function to run continously.
// To avoid that problem, you can use a memoized function provided by `React.useCallback` or a class method
// The code below is an example that inline function can result in an infinite loop and the verify function runs continously:

const MyComponent: FC = () => {
  const [token, setToken] = useState();

  return (
    <div>
      <GoogleReCaptcha
        onVerify={token => {
          setToken(token);
        }}
      />
    </div>
  );
};

React Hook: useGoogleReCaptcha (recommended approach)

If you prefer a React Hook approach over the old good Higher Order Component, you can choose to use the custom hook useGoogleReCaptcha over the HOC withGoogleReCaptcha.

The executeRecaptcha function returned from the hook can be undefined when the recaptcha script has not been successfully loaded. You can do a null check to see if it's available or not.

How to use the hook:

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

const YourReCaptchaComponent = () => {
  const { executeRecaptcha } = useGoogleReCaptcha();

  // Create an event handler so you can call the verification on button click event or form submit
  const handleReCaptchaVerify = useCallback(async () => {
    if (!executeRecaptcha) {
      console.log('Execute recaptcha not yet available');
    }

    const token = await executeRecaptcha('yourAction');
    // Do whatever you want with the token
  }, []);

  // You can use useEffect to trigger the verification as soon as the component being loaded
  useEffect(() => {
    handleReCaptchaVerify();
  }, [handleReCaptchaVerify]);

  return <button onClick={handleRecaptchaVerify}>Verify recaptcha</button>;
};

ReactDom.render(
  <GoogleReCaptchaProvider reCaptchaKey="[Your recaptcha key]">
    <YourReCaptchaComponent />
  </GoogleReCaptchaProvider>,
  document.getElementById('app')
);

withGoogleReCaptcha

GoogleRecaptcha is a HOC (higher order component) that can be used to integrate reCaptcha validation with your component and trigger the validation programmatically. It inject the wrapped component with googleReCaptchaProps object.

The object contains the executeRecaptcha function that can be called to validate the user action.

You are recommended to use the custom hook useGoogleReCaptcha over the HOC whenever you can. The HOC can be removed in future version.

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

class ReCaptchaComponent extends Component<{}> {
  handleVerifyRecaptcha = async () => {
    const { executeRecaptcha } = (this.props as IWithGoogleReCaptchaProps)
      .googleReCaptchaProps;

    if (!executeRecaptcha) {
      console.log('Recaptcha has not been loaded');

      return;
    }

    const token = await executeRecaptcha('homepage');
  };

  render() {
    return (
      <div>
        <button onClick={this.handleVerifyRecaptcha}>Verify Recaptcha</button>
      </div>
    );
  }
}

export const WithGoogleRecaptchaExample =
  withGoogleReCaptcha(ReCaptchaComponent);

ReactDom.render(
  <GoogleReCaptchaProvider reCaptchaKey="[Your recaptcha key]">
    <WithGoogleRecaptchaExample />
  </GoogleReCaptchaProvider>,
  document.getElementById('app')
);

Example

An example of how to use these two hooks can found inside the example folder. You will need to provide an .env file if you want to run it on your own machine.

RECAPTCHA_KEY=[YOUR_RECAPTCHA_KEY]