react-google-recaptcha

React component for Google reCAPTCHA v2.

Installation

npm install --save react-google-recaptcha

Usage

All you need to do is sign up for an API key pair. You will need the client key then you can use <ReCAPTCHA />.

The default usage imports a wrapped component that loads the google recaptcha script asynchronously then instantiates a reCAPTCHA the user can then interact with.

Code Example:

import ReCAPTCHA from "react-google-recaptcha";

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

ReactDOM.render(
  <ReCAPTCHA
    sitekey="Your client site key"
    onChange={onChange}
  />,
  document.body
);

Component Props

Properties used to customise the rendering:

Component Instance API

The component instance also has some utility functions that can be called. These can be accessed via ref.

• getValue() returns the value of the captcha field
• getWidgetId() returns the recaptcha widget Id
• reset() forces reset. See the JavaScript API doc
• execute() programmatically invoke the challenge
  • need to call when using "invisible" reCAPTCHA - example below
• executeAsync() programmatically invoke the challenge and return a promise that resolves to the token or errors(if encountered).
  • alternative approach to execute() in combination with the onChange() prop - example below

Example:

const recaptchaRef = React.createRef();
...
onSubmit = () => {
  const recaptchaValue = recaptchaRef.current.getValue();
  this.props.onSubmit(recaptchaValue);
}
render() {
  return (
    <form onSubmit={this.onSubmit} >
      <ReCAPTCHA
        ref={recaptchaRef}
        sitekey="Your client site key"
        onChange={onChange}
      />
    </form>
  )
}

Invisible reCAPTCHA

▶ Codesandbox invisible example

See the reCAPTCHA documentation to see how to configure it.

With the invisible option, you need to handle things a bit differently. You will need to call the execute method yourself.

import ReCAPTCHA from "react-google-recaptcha";

const recaptchaRef = React.createRef();

ReactDOM.render(
  <form onSubmit={() => { recaptchaRef.current.execute(); }}>
    <ReCAPTCHA
      ref={recaptchaRef}
      size="invisible"
      sitekey="Your client site key"
      onChange={onChange}
    />
  </form>,
  document.body
);

Additionally, you can use the executeAsync method to use a promise based approach.

import ReCAPTCHA from "react-google-recaptcha";


const ReCAPTCHAForm = (props) => {
  const recaptchaRef = React.useRef();

  const onSubmitWithReCAPTCHA = async () => {
    const token = await recaptchaRef.current.executeAsync();

    // apply to form data
  }

  return (
    <form onSubmit={onSubmitWithReCAPTCHA}>
      <ReCAPTCHA
        ref={recaptchaRef}
        size="invisible"
        sitekey="Your client site key"
      />
    </form>
  )

}

ReactDOM.render(
  <ReCAPTCHAForm />,
  document.body
);

Advanced usage

Global properties used by reCaptcha

useRecaptchaNet: If google.com is blocked, you can set useRecaptchaNet to true so that the component uses recaptcha.net instead.

Example global properties:

window.recaptchaOptions = {
  useRecaptchaNet: true,
};

ReCaptcha loading google recaptcha script manually

You can also use the barebone components doing the following. Using that component will oblige you to manage the grecaptcha dep and load the script by yourself.

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

const grecaptchaObject = window.grecaptcha // You must provide access to the google grecaptcha object.

render(
  <ReCAPTCHA
    ref={(r) => this.recaptcha = r}
    sitekey="Your client site key"
    grecaptcha={grecaptchaObject}
  />,
  document.body
);

Hiding the Recaptcha

According to the google docs you are allowed to hide the badge as long as you include the reCAPTCHA branding visibly in the user flow. Please include the following text:

This site is protected by reCAPTCHA and the Google
    <a href="https://policies.google.com/privacy">Privacy Policy</a> and
    <a href="https://policies.google.com/terms">Terms of Service</a> apply.

If you wish to hide the badge you must add:

.grecaptcha-badge { visibility: hidden; }

to your css.

Migrate to 2.0

• options.removeOnUnmount: REMOVED This was only useful for the lang changes. Lang is now changed through the hl prop.
• options.lang: REMOVED Instead pass it as the hl prop on the component.

Notes on Requirements

At least [email protected] is required due to forwardRef usage in the dependency react-async-script.

Notes

Pre 1.0.0 and React < 16.4.1 support details in 0.14.0.