Registry / auth-security / react-google-recaptcha

react-google-recaptcha

library3.1.0jsnpmunverified

react-google-recaptcha is a React component wrapper for Google reCAPTCHA v2, simplifying its integration into web applications. Currently stable at version 3.1.0, it abstracts away the asynchronous loading of the reCAPTCHA JavaScript API and provides a declarative API for rendering and interacting with reCAPTCHA widgets. The library offers props for customizing widget appearance (theme, size, type), language, and badge positioning, as well as callbacks for success (`onChange`), expiration (`onExpired`), and errors (`onErrored`). It also exposes an instance API via React refs for programmatic actions like `reset()`, `getValue()`, `execute()`, and `executeAsync()`, which are particularly useful for invisible reCAPTCHA implementations. Its primary differentiator is streamlining the often complex reCAPTCHA setup into a standard React component lifecycle, reducing boilerplate and common integration pitfalls.

auth-security web-framework

npm install react-google-recaptcha

github ↗package ↗

INSTALL

IMPORT

SIG · REACT-GOOGLE-RECAP

react-google-recaptcha

auth-securityjavascriptv3.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ReCAPTCHA

✓ import ReCAPTCHA from 'react-google-recaptcha';

✗ import { ReCAPTCHA } from 'react-google-recaptcha';

ReCAPTCHA is exported as a default export.

reCAPTCHA onChange event handler

✓ function onChange(value) { console.log('Captcha value:', value); }

The onChange prop expects a function that receives the reCAPTCHA token as its first argument.

reCAPTCHA ref methods (getValue, reset, execute)

✓ const recaptchaRef = React.createRef(); recaptchaRef.current.getValue();

Access instance methods like getValue(), reset(), or execute() via a React ref to the ReCAPTCHA component.

Initializes and renders a visible Google reCAPTCHA v2 widget, logging the token on successful completion, expiration, or error. Requires a `root` element or will create one.

import React from 'react'; import ReactDOM from 'react-dom'; import ReCAPTCHA from 'react-google-recaptcha'; const RECAPTCHA_SITE_KEY = process.env.RECAPTCHA_SITE_KEY ?? '6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXwpTqiT'; // Example key function App() { function onChange(value) { console.log('Captcha value:', value); // In a real application, send this 'value' (token) to your backend for verification. } function onExpired() { console.log('reCAPTCHA challenge expired.'); } function onErrored(error) { console.error('reCAPTCHA challenge errored:', error); } return ( <div> <h1>React Google reCAPTCHA Example</h1> <p>Please complete the reCAPTCHA to proceed.</p> <ReCAPTCHA sitekey={RECAPTCHA_SITE_KEY} onChange={onChange} onExpired={onExpired} onErrored={onErrored} theme="light" size="normal" /> <p>Note: This sitekey is for demonstration only. Use your own client site key registered with Google reCAPTCHA.</p> </div> ); } ReactDOM.render(<App />, document.getElementById('root') || document.createElement('div'));

Debug

Known issues

gotchareCAPTCHA tokens obtained from the client-side `onChange` callback MUST be verified on a backend server using Google's reCAPTCHA API. Client-side validation alone is insecure and easily bypassed.

fix

Implement a server-side endpoint to receive the reCAPTCHA token and verify it with `https://www.google.com/recaptcha/api/siteverify` before processing any sensitive user action.

affects: >=1.0.0

gotchareCAPTCHA tokens are typically one-time use. After a successful submission and backend verification, the reCAPTCHA widget must be manually reset using `recaptchaRef.current.reset()` to allow subsequent submissions.

fix

Call `recaptchaRef.current.reset()` in your component's logic after your backend successfully validates the token and completes the user action.

affects: >=1.0.0

gotchaFor 'invisible' reCAPTCHA (`size="invisible"`), the challenge will not automatically trigger. You must programmatically invoke it using `recaptchaRef.current.execute()` or `recaptchaRef.current.executeAsync()`.

fix

Ensure you call `recaptchaRef.current.execute()` (typically on a form submission) when using `size="invisible"`. Integrate this with your form's submission handler.

affects: >=1.0.0

gotchaUsing multiple `ReCAPTCHA` instances on the same page can lead to conflicts. If embedding the component within a plugin or widget, use the `isolated` prop.

fix

Set the `isolated={true}` prop on your `ReCAPTCHA` component if there's a possibility of other reCAPTCHA instances on the host page where your component is embedded.

affects: >=1.0.0

deprecatedThis library is specifically for Google reCAPTCHA v2. While v2 is still supported, Google has released reCAPTCHA v3 which operates differently (score-based, no user interaction). If you need v3, you will need a different library or custom integration.

fix

If reCAPTCHA v3 functionality is required, consider using a library specifically designed for v3 or integrating the v3 API directly.

affects: >=1.0.0

Errors

Common errors & fixes

Error: reCAPTCHA has already been rendered in this element

Attempting to render multiple reCAPTCHA widgets into the same DOM element or having conflicting reCAPTCHA instances without proper isolation.

fix

Ensure each `ReCAPTCHA` component renders into a unique DOM location. If embedding, consider using the `isolated` prop set to `true`.

reCAPTCHA widget does not appear, or network errors in console (e.g., 'Failed to load resource')

The `sitekey` prop is missing, incorrect, or not registered correctly with Google reCAPTCHA for the current domain. Alternatively, network issues, ad blockers, or Content Security Policy (CSP) restrictions might be preventing the script from loading.

fix

Double-check the `sitekey` value against your Google reCAPTCHA admin console and ensure the domain registration matches. Verify your browser console for network errors or CSP warnings, and ensure your CSP allows loading scripts from `www.google.com/recaptcha/api.js`.

TypeError: Cannot read properties of null (reading 'getValue')

Attempting to call `recaptchaRef.current.getValue()` or other instance methods before the component is fully mounted and the ref has been assigned.

fix

Ensure the ref is properly initialized and the component is mounted before accessing `recaptchaRef.current`. For functional components, use `useRef` and ensure the code accessing the ref runs after the component has rendered (e.g., within an `useEffect` or an event handler triggered after mount).

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React applications.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dozoisch/react-google-recaptcha ↗

packagehttps://www.npmjs.com/package/react-google-recaptcha ↗