react-hcaptcha

The react-hcaptcha library provides a React component for integrating hCaptcha into your applications. hCaptcha is a privacy-focused alternative to reCAPTCHA.

Prerequisite: You must sign up at hCaptcha to obtain a sitekey. This library cannot be used without a valid sitekey.

Install the library using npm to add it to your project:

npm install @hcaptcha/react-hcaptcha --save

The HCaptcha component is the primary entry point for integrating hCaptcha into a React application. It handles script loading, widget rendering, and provides a bridge to the underlying hCaptcha API. You can pass various configuration props to customize the widget's appearance, behavior, and callbacks.

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

function MyForm() {
  const handleVerify = (token, ekey) => {
    console.log('Verification token:', token);
    console.log('Response key:', ekey);
  };

  return (
    <HCaptcha
      sitekey="YOUR_SITE_KEY"
      onVerify={handleVerify}
      onExpire={() => console.log('Captcha expired')}
      onError={(err) => console.error('Captcha error:', err)}
    />
  );
}

If the sentry prop is enabled, the hcaptcha-loader package requires Sentry SDK version 8.x or later. If your site uses an older @sentry/browser version, you may see the error g.setPropagationContext is not a function.

Solutions:

1. Update your Sentry client to version 8.x or higher.
2. Set the sentry prop to false on the <HCaptcha /> component to avoid using the bundled Sentry logic.

The simplest way to use hCaptcha is to include the <HCaptcha /> component within a parent element (like a <form />). You must provide a sitekey. The component automatically handles loading the hCaptcha API library.

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

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

To call the hCaptcha client API directly (e.g., to trigger a challenge manually), use the useRef hook. It is critical to wait for the onLoad callback to ensure the hCaptcha API is fully loaded and the client is set up before calling methods like .execute().

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 = () => {
    // Reaches out to the hCaptcha JS API and runs the execute function
    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>
  );
}

For a cleaner architecture, you can wrap your application (or a section of it) in an HCaptchaProvider. This allows any child component to access hCaptcha state and methods via the useHCaptcha hook.

import { HCaptchaProvider, useHCaptcha } from '@hcaptcha/react-hcaptcha';

function App() {
  return (
    <HCaptchaProvider sitekey="your-sitekey">
      <Form />
    </HCaptchaProvider>
  );
}

function Form() {
  const { ready, token, executeInstance } = useHCaptcha();

  const onSubmit = async () => {
    const response = await executeInstance();
    console.log("Token:", response);
  };

  return <button onClick={onSubmit} disabled={!ready}>Submit</button>;
}