react-multi-captcha

A lightweight React component supporting multiple captcha providers: Google reCAPTCHA, hCaptcha, and Cloudflare Turnstile.

Features

Support for Google reCAPTCHA v2, hCaptcha, and Cloudflare Turnstile
TypeScript support with full type definitions
Ref API for programmatic control (reset, execute, getResponse)
Automatic script loading with deduplication
Zero runtime dependencies
Works with React 18 and React 19

Installation

npm install react-multi-captcha
# or
yarn add react-multi-captcha

Usage

Basic Usage

import { Captcha } from "react-multi-captcha";

function LoginForm() {
  const handleVerify = (token: string) => {
    console.log("Captcha verified:", token);
  };

  return (
    <Captcha
      provider="google"
      siteKey="your-site-key"
      onVerify={handleVerify}
    />
  );
}

With Ref for Programmatic Control

import { useRef } from "react";
import { Captcha, CaptchaRef } from "react-multi-captcha";

function Form() {
  const captchaRef = useRef<CaptchaRef>(null);

  const handleSubmit = async () => {
    // Get current response
    const token = captchaRef.current?.getResponse();

    if (!token) {
      // Execute invisible captcha
      const newToken = await captchaRef.current?.execute();
    }

    // Submit form...
  };

  const handleReset = () => {
    captchaRef.current?.reset();
  };

  return (
    <form onSubmit={handleSubmit}>
      <Captcha
        ref={captchaRef}
        provider="hcaptcha"
        siteKey="your-site-key"
        onVerify={(token) => console.log(token)}
      />
      <button type="button" onClick={handleReset}>
        Reset Captcha
      </button>
      <button type="submit">Submit</button>
    </form>
  );
}

With All Options

import { Captcha } from "react-multi-captcha";

function Form() {
  return (
    <Captcha
      provider="cloudflare"
      siteKey="your-site-key"
      onVerify={(token) => console.log("Verified:", token)}
      onError={(error) => console.error("Error:", error)}
      onExpire={() => console.log("Token expired")}
      onLoad={() => console.log("Captcha loaded")}
      theme="dark"
      size="normal"
      language="pt-BR"
      tabIndex={0}
      className="my-captcha"
      style={{ marginTop: "1rem" }}
    />
  );
}

Props

Prop	Type	Required	Default	Description
`provider`	`"google" \| "hcaptcha" \| "cloudflare"`	Yes	-	Captcha provider to use
`siteKey`	`string`	Yes	-	Site key from the captcha provider
`onVerify`	`(token: string) => void`	Yes	-	Callback when verification succeeds
`onError`	`(error: Error) => void`	No	-	Callback when an error occurs
`onExpire`	`() => void`	No	-	Callback when the token expires
`onLoad`	`() => void`	No	-	Callback when the widget loads
`theme`	`"light" \| "dark" \| "auto"`	No	`"light"`	Widget theme
`size`	`"normal" \| "compact" \| "invisible"`	No	`"normal"`	Widget size
`language`	`string`	No	-	Language code (e.g., "en", "pt-BR")
`tabIndex`	`number`	No	-	Tab index for accessibility
`className`	`string`	No	-	Additional CSS class names
`style`	`CSSProperties`	No	-	Inline styles for the container

Ref Methods

Method	Type	Description
`reset`	`() => void`	Reset the captcha widget
`execute`	`() => Promise<string>`	Execute invisible captcha and get token
`getResponse`	`() => string \| null`	Get the current response token

Provider-Specific Notes

Google reCAPTCHA

Uses reCAPTCHA v2 ("I'm not a robot" checkbox)
Get your site key from Google reCAPTCHA Admin

hCaptcha

Privacy-focused alternative to reCAPTCHA
Get your site key from hCaptcha Dashboard

Cloudflare Turnstile

Non-interactive, privacy-preserving captcha
Get your site key from Cloudflare Dashboard

License

MIT