Reaptcha

A clean, modern and simple React wrapper for Google reCAPTCHA.

Demo

https://jsardev.github.io/reaptcha/

Motivation

I've been using other React wrappers for reCAPTCHA like react-recaptcha or react-google-recaptcha but unfortunately both of them provide a non-react way (declaring the callbacks outside React components, not inside them) to handle all the reCAPTCHA callbacks which didn't feel clean and I didn't like this approach personally.

This is why I've decided to give it a try to create a cleaner approach and this is the result.

Features

All callbacks in your React component
100% test coverage
Automatic reCAPTCHA script injection and cleanup
Usable with multiple reCAPTCHA instances
Full control over every reCAPTCHA instance
reCAPTCHA instance methods with promises and clean error messages
SSR ready

Installation

Just install the package with npm:

npm install --save reaptcha

or with yarn:

yarn add reaptcha

Usage

IMPORTANT NOTE: Reaptcha injects reCAPTCHA script into DOM automatically by default. If you are doing it manually, check out this description.

First of all, you'll need a reCAPTCHA API key. To find out how to get it

check this guide.

To see how Reaptcha actually works, visit the example page.

If you'd also like to see the code for the example, it is right here.

Default - Automatic render

By default Reaptcha injects the reCAPTCHA script into your head DOM element and renders a I'm a robot captcha.

Here's a quick example how can you use Reaptcha to verify your form submission:

import React, { Component } from 'react';
import Reaptcha from 'reaptcha';

class MyForm extends Component {
  constructor(props) {
    super(props);
    this.state = {
      verified: false
    };
  }

  onVerify = recaptchaResponse => {
    this.setState({
      verified: true
    });
  };

  render() {
    return (
      <form>
        <Reaptcha sitekey="YOUR_API_KEY" onVerify={this.onVerify} />
        <button type="submit" disabled={!this.state.verified}>
          Submit
        </button>
      </form>
    );
  }
}

Explicit render

In order to render Reaptcha explicitly, you need to pass the explicit prop, store the reference to the instance and call the renderExplicitly function manually.

Caution! In order to prevent race-conditions, make sure you render the reCAPTCHA after the script successfuly loads. To do that, pass a function the the onLoad prop where you'll get informed that everything is ready to render.

Here's an example:

import React, { Fragment, Component } from 'react';
import Reaptcha from 'reaptcha';

class MyForm extends Component {
  constructor(props: Props) {
    super(props);
    this.captcha = null;
    this.state = {
      captchaReady: false
    };
  }

  onLoad = () => {
    this.setState({
      captchaReady: true
    });
  };

  onVerify = recaptchaResponse => {
    // Do something
  };

  render() {
    return (
      <Fragment>
        <Reaptcha
          ref={e => (this.captcha = e)}
          sitekey="YOUR_API_KEY"
          onLoad={this.onLoad}
          onVerify={this.onVerify}
          explicit
        />
        <button
          onClick={() => {
            this.captcha.renderExplicitly();
          }}
          disabled={this.state.recaptchaReady}
        >
          Render reCAPTCHA
        </button>
      </Fragment>
    );
  }
}

Invisible

When you want to have an invisible reCAPTCHA, you'll have to execute it manually (as user won't have any possibility to do it). This can be done similarly to explicit rendering - saving the reference to the Reaptcha instance and call the execute method on it.

Additionally, invisible reCAPTCHA can be of course also rendered automatically or explicitly - this is your choice and the reference how to do it is right above.

import React, { Fragment, Component } from 'react';
import Reaptcha from 'reaptcha';

class MyForm extends Component {
  constructor(props: Props) {
    super(props);
    this.captcha = null;
  }

  onVerify = recaptchaResponse => {
    // Do something
  };

  render() {
    return (
      <Fragment>
        <Reaptcha
          ref={e => (this.captcha = e)}
          sitekey="YOUR_API_KEY"
          onVerify={this.onVerify}
          size="invisible"
        />
        <button
          onClick={() => {
            this.captcha.execute();
          }}
        >
          Execute reCAPTCHA
        </button>
      </Fragment>
    );
  }
}

Reset

You can also manually reset your reCAPTCHA instance. It's similar to executing it:

<Fragment>
  <Reaptcha
    ref={e => (this.captcha = e)}
    sitekey="YOUR_API_KEY"
    onVerify={recaptchaResponse => {
      // Do something
    }}
  />
  <button onClick={() => this.captcha.reset()}>Reset</button>
</Fragment>

Instance methods

It's known that calling methods of a React component class is a really bad practice, but as we're doing something uncommon to typical React components - it's the only method that popped in that actually is intuitive and React-ish.

So to get access to the methods, just save the reference to the component instance:

<Reaptcha ref={e => (this.captcha = e)} />

If you have an idea how to do this better, feel free to file an issue to discuss it!

Available and usable Reaptcha instance methods:

| Name | Returns | Description | | ---------------- | ----------------- | ----------------------------------------- | | renderExplicitly | Promise<void> | Renders the reCAPTCHA instance explicitly | | reset | Promise<void> | Resets the reCAPTCHA instance | | execute | Promise<void> | Executes the reCAPTCHA instance | | getResponse | Promise<string> | Returns the reCATPCHA response |

Render prop

Using instance methods can be avoided by passing children render function.

<Reaptcha>
  {({ renderExplicitly, reset, execute, recaptchaComponent }) => {
    return (
      <div>
        {recaptchaComponent}

        <button onClick={reset}>Reset</button>
      </div>
    );
  }}
</Reaptcha>

When passing children render prop, you are responsible for rendering recaptchaComponent into the DOM.

Customisation

Reaptcha allows to customize your reCAPTCHA instances with any available properties documented in the reCAPTCHA docs for all of the types:

| Name | Required | Type | Default | Description | | --------- | ------------------ | ------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | :heavy_minus_sign: | string | - | Id for the container element | | className | :heavy_minus_sign: | string | 'g-recaptcha' | Classname for the container element | | sitekey | :heavy_plus_sign: | string | - | Your reCAPTCHA API key | | theme | :heavy_minus_sign: | 'light' \| 'dark' | 'light' | reCAPTCHA color theme | | size | :heavy_minus_sign: | 'compact' \| 'normal' \| 'invisible' | 'normal' | reCAPTCHA size | | badge | :heavy_minus_sign: | 'bottomright' \| 'bottomleft' \| 'inline' | 'bottomright' | Position of the reCAPTCHA badge