react-google-recaptcha

react-google-recaptcha wraps Google’s reCAPTCHA v2 widget in a single React component, so forms get bot protection without hand-rolling script injection or imperative DOM calls to the grecaptcha global. The default export composes a script-loader higher-order component (built on the author’s own react-async-script package) with the widget component itself, so dropping in <ReCAPTCHA sitekey="..." onChange={...} /> is enough to get a working checkbox challenge, invisible challenge, or Google Enterprise reCAPTCHA.

Beyond the basic checkbox flow, it exposes the full underlying grecaptcha surface through a ref API — getValue, reset, execute, and a promise-based executeAsync — which lets consumers drive invisible reCAPTCHA from a submit handler, reset the widget after a failed submission, or await a token before firing off a request. Global configuration via window.recaptchaOptions covers CSP nonces, recaptcha.net fallback for blocked regions, and enterprise mode, making it usable across most real-world deployment constraints without forking the library.

What You Get

• A default-exported component that auto-injects the reCAPTCHA script and renders the widget once loaded — no manual <script> tag needed
• A named ReCAPTCHA export for consumers who want to manage script loading themselves and pass in an existing grecaptcha object
• Ref-accessible imperative methods: getValue(), getWidgetId(), reset(), forceReset(), execute(), and a promise-based executeAsync()
• Support for normal, compact, and invisible sizes, light/dark themes, and Google Enterprise reCAPTCHA via a single enterprise flag
• CSP nonce support and a recaptcha.net fallback hostname for regions where google.com is blocked

Common Use Cases

• Adding a checkbox reCAPTCHA challenge to a signup, login, or contact form to deter automated abuse
• Driving an invisible reCAPTCHA challenge from a form’s submit handler via execute()/executeAsync()
• Resetting the widget after a failed server-side validation so the user can retry without a full page reload
• Switching to Google Enterprise reCAPTCHA for risk-based scoring without changing the component’s public API

Under The Hood

Architecture The library exposes a class component ReCAPTCHA (src/recaptcha.js) that renders a bare <div> ref and imperatively calls Google’s grecaptcha.render() inside componentDidMount/componentDidUpdate (the explicitRender method), storing the returned widget id for later use by getValue, reset, execute, and executeAsync. The default export (src/recaptcha-wrapper.js) wraps that class with react-async-script’s makeAsyncScriptLoader higher-order component, which injects the script tag with a global callback name and passes the loaded grecaptcha object down as a prop once it fires — decoupling script-loading concerns from widget-rendering concerns into two composable layers. src/index.js re-exports the wrapped component as default and the bare class as a named export for consumers managing their own script loading. There’s no internal state store or router — it’s a thin imperative-bridge pattern (React ref plus a third-party global JS API), so the only thing that breaks if the core abstraction changes is the widget-id bookkeeping and callback wiring inside recaptcha.js.

Tech Stack Plain JavaScript (no TypeScript) targeting React 16.4.1+ as a peer dependency, built with Babel into both CommonJS (lib/) and ESM (lib/esm/) output via separate build scripts driven by a BABEL_ENV flag. Runtime dependencies are minimal — prop-types for prop validation and react-async-script (the same author’s companion package) for script loading. Testing runs on Jest with jest-environment-jsdom and Testing Library. Linting and formatting are enforced via ESLint and Prettier, and CI (GitHub Actions) runs the test suite across multiple Node versions and operating systems.

Code Quality Tests exist and cover the meaningful surface area: widget rendering, prop pass-through, the full ref-based API, error/expired callback branches, and enterprise mode, spread across dedicated spec files for the widget and the script-loader wrapper. Error handling is minimal but explicit — executeAsync’s promise rejects through a stored rejection callback on the underlying error callback, and helper methods guard against a missing grecaptcha object rather than throwing. There’s no TypeScript, so type safety for consumers comes only from runtime PropTypes checks. Naming is consistent, mirroring the underlying grecaptcha API surface, and ESLint/Prettier plus CI gating provide a baseline quality floor despite the lack of static types.

API Design The public API mirrors Google’s own imperative grecaptcha API almost one-to-one, which keeps the learning curve low for anyone already familiar with Google’s docs, at some cost to feeling idiomatic for a React library — imperative ref calls rather than declarative props and state. Getting started needs nothing beyond a sitekey prop and a change handler, since the default export handles script injection automatically. Global configuration through window.recaptchaOptions for enterprise mode, the recaptcha.net fallback, and CSP nonces sits outside normal React prop flow, but it is clearly documented in the README with runnable examples for both standard and invisible reCAPTCHA usage.