React hCaptcha Component Library

hCaptcha Component Library for ReactJS.

hCaptcha is a drop-replacement for reCAPTCHA that protects user privacy.

Sign up at hCaptcha to get your sitekey today. You need a sitekey to use this library.

Also compatible with Preact.

1. Installation
2. References
3. Debugging
4. Contributing

Installation

You can install this library via npm with:

npm install @hcaptcha/react-hcaptcha --save

Implementation

The two requirements for usage are the sitekey prop and a parent component such as a <form />. The component will automatically include and load the hCaptcha API library and append it to the parent component. This is designed for ease of use with the hCaptcha API!

Standard

import HCaptcha from '@hcaptcha/react-hcaptcha';

<FormComponent>
    <HCaptcha
      sitekey="your-sitekey"
      onVerify={(token,ekey) => handleVerificationSuccess(token, ekey)}
    />
</FormComponent>

Programmatic

In the event you want to call the hCaptcha client API directly, you can do so by using the hook useRef and waiting for onLoad to be called. By waiting for onLoad the hCaptcha API will be ready and the hCaptcha client will have been setup. See the following example:

import { useEffect, useRef, useState } from "react";
import HCaptcha from "@hcaptcha/react-hcaptcha";

export default function Form() {
  const [token, setToken] = useState(null);
  const captchaRef = useRef(null);

  const onLoad = () => {
    // this reaches out to the hCaptcha JS API and runs the
    // execute function on it. you can use other functions as
    // documented here:
    // https://docs.hcaptcha.com/configuration#jsapi
    captchaRef.current.execute();
  };

  useEffect(() => {

    if (token)
      console.log(`hCaptcha Token: ${token}`);

  }, [token]);

  return (
    <form>
      <HCaptcha
        sitekey="your-sitekey"
        onLoad={onLoad}
        onVerify={setToken}
        ref={captchaRef}
      />
    </form>
  );
}

Typescript Support \ If you want to reassign the component name, you could consider making a util that imports the component, then re-exports it as a default.

// utils/captcha.ts
import HCaptcha from '@hcaptcha/react-hcaptcha';
export default HCaptcha;

// MyFormComponent.tsx
import { default as RenamedCaptcha } from '../utils/captcha';
<FormComponent>
  <RenamedCaptcha sitekey="your-sitekey" />
</FormComponent>

Advanced

In most real-world implementations, you'll probably be using a form library such as Formik or React Hook Form.

In these instances, you'll most likely want to use ref to handle the callbacks as well as handle field-level validation of a captcha field. For an example of this, you can view this CodeSandbox. This ref will point to an instance of the hCaptcha API where can you interact directly with it.

Passing in fields like rqdata to execute()

Passing an object into the execute(yourObj) call will send it through to the underlying JS API. This enables support for Enterprise features like rqdata. A simple example is below:

const {sitekey, rqdata} = props;
const captchaRef = React.useRef<HCaptcha>(null);

const onLoad = () => {
  const executePayload = {};
  if (rqdata) {
    executePayload['rqdata'] = rqdata;
  }
  captchaRef.current?.execute(executePayload);
};

return <HCaptcha ref={captchaRef} onLoad={onLoad} sitekey={sitekey} {...props} />;

References

Props

Events

Methods

Note \ Make sure to reset the hCaptcha state when you submit your form by calling the method .resetCaptcha on your hCaptcha React Component! Passcodes are one-time use, so if your user submits the same passcode twice then it will be rejected by the server the second time.

Please refer to the demo for examples of basic usage and an invisible hCaptcha.

Alternatively, see this sandbox code for a quick form example of invisible hCaptcha on a form submit button.

Please note that "invisible" simply means that no hCaptcha button will be rendered. Whether a challenge shows up will depend on the sitekey difficulty level. Note to hCaptcha Enterprise (BotStop) users: select "Passive" or "99.9% Passive" modes to get this No-CAPTCHA behavior.

Debugging

1. Invalid hCaptcha Id:

   This issue generally occurs when the component is re-rendered causing the current useRef to become stale, meaning the ref being used is no longer available in the DOM.

2. Make sure you don't double-import the api.js script

   Importing the JS SDK twice can cause unpredictable behavior, so don't do a direct import separately if you are using react-hcaptcha.

3. Make sure you are using reCaptchaCompat=false if you have the reCAPTCHA JS loaded on the same page.

   The hCaptcha "compatibility mode" will interfere with reCAPTCHA, as it adds properties with the same name. If for any reason you are running both hCaptcha and reCAPTCHA in parallel (we recommend only running hCaptcha) then please disable our compatibility mode.

4. Avoid conflicts with legacy Sentry package usage on react-hcaptcha 1.9.0+

   If you are using Sentry 7.x in your React app, this can conflict with the upstream hcaptcha-loader package's Sentry error tracing. You can avoid this issue by setting the sentry prop to false.

Contributing

Scripts

• npm run start - will start the demo app with hot reload
• npm run test - will test the library: unit tests
• npm run build - will build the production version

Publishing

To publish a new version, follow the next steps:

1. Bump the version in package.json
2. Create a Github Release with version from step 1 without a prefix such as v (e.g. 1.0.3)
   • publish workflow will be triggered which will: build, test and deploy the package to the npm @hcaptcha/react-hcaptcha.

Running locally for development

Please see: Local Development Notes.

Summary:

sudo echo "127.0.0.1 fakelocal.com" >> /private/etc/hosts
npm start -- --disable-host-check

open http://fakelocal.com:9000 to start the example.