react-google-recaptcha-v3

react-google-recaptcha-v3 is a thin TypeScript wrapper around Google’s reCAPTCHA v3 (and reCAPTCHA Enterprise) JavaScript API for React applications. It injects and manages the reCAPTCHA script’s lifecycle, exposing a single executeRecaptcha function through three interchangeable consumption patterns: a GoogleReCaptchaProvider context provider, the recommended useGoogleReCaptcha hook, a declarative GoogleReCaptcha component, and a legacy withGoogleReCaptcha higher-order component.

Because reCAPTCHA v3 runs invisibly and scores user interactions rather than presenting a challenge, the library’s main job is plumbing: loading the script exactly once per page, tearing it down cleanly on unmount, and re-executing verification on demand (via a refreshReCaptcha prop) after actions like form submission. It also supports recaptcha.net as a script host for regions where google.com is blocked, and custom badge placement/theming for teams that need to move the default floating badge.

What You Get

• A GoogleReCaptchaProvider component that loads the reCAPTCHA (or reCAPTCHA Enterprise) script once and cleans it up on unmount
• The useGoogleReCaptcha hook, the recommended way to call executeRecaptcha(action) and retrieve a verification token
• A declarative GoogleReCaptcha component with an onVerify callback and a refreshReCaptcha prop to force re-validation
• A withGoogleReCaptcha higher-order component for class-based components that injects googleReCaptchaProps
• Support for recaptcha.net as an alternate script host and for rendering/positioning a custom badge container

Common Use Cases

• Protecting login and signup forms from bot submissions without showing a visible challenge
• Guarding contact forms, comment sections, and newsletter signups against spam
• Re-validating a token immediately before a sensitive action (checkout, password reset) using refreshReCaptcha
• Migrating a self-hosted or region-restricted app to recaptcha.net or reCAPTCHA Enterprise scoring

Under The Hood

Architecture The library is organized as one file per concern: google-recaptcha-provider.tsx implements a React Context provider whose useEffect owns the reCAPTCHA script’s entire lifecycle (inject on mount, clean up badge/script/window globals on unmount), use-google-recaptcha.tsx is a one-line hook over that context, with-google-recaptcha.tsx wraps the same context in a class-compatible HOC via hoist-non-react-statics, and google-recaptcha.tsx layers a declarative onVerify/refreshReCaptcha component on top of the hook. utils.ts isolates every DOM-touching function (script tag creation, badge removal, gstatic script cleanup) as framework-agnostic pure functions callable independently of React. Every consumer path funnels through the same memoized context value, so the provider is the single point of truth an app depends on.

Tech Stack Written in TypeScript and built with Rollup (rollup-plugin-typescript2, rollup-plugin-commonjs, rollup-plugin-node-resolve, rollup-plugin-terser) into paired ESM and CJS bundles plus a generated .d.ts entry point, published for React 16.3 through 19 as peer dependencies. The only runtime dependency is hoist-non-react-statics, used solely to preserve static members through the HOC wrapper. A separate Webpack config builds a standalone example app for manual testing against a live reCAPTCHA key.

Code Quality Jest with ts-jest and React Testing Library covers the provider, the hook, and the HOC in three focused test files, each asserting the context/props shape rather than DOM behavior in depth. Errors are explicit: missing script availability or an uninitialized context throw descriptive Errors rather than failing silently, and non-critical issues route through a logWarningMessage helper that no-ops outside development. Linting still relies on the long-deprecated tslint rather than ESLint, and there is no CI workflow configured in the repository, so quality enforcement depends on the maintainer running checks locally before publishing.

API Design The library offers three ways to reach the same executeRecaptcha function — hook, declarative component, and HOC — covering hooks-based, JSX-declarative, and legacy class-based codebases without forcing a rewrite. Getting started needs only a provider wrapping the app plus a hook call, and prop tables in the README document every option (script placement, nonce, badge theme/position, Enterprise mode) with sensible defaults so the common case requires almost no configuration.