Registry /
auth-security / react-google-recaptcha-v3
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GoogleReCaptchaProvider
✓ import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
✗ const { GoogleReCaptchaProvider } = require('react-google-recaptcha-v3');
This component should wrap your application or relevant parts to provide reCAPTCHA context. Place it high in the component tree to avoid reloads.
useGoogleReCaptcha
✓ import { useGoogleReCaptcha } from 'react-google-recaptcha-v3';
✗ import useGoogleReCaptcha from 'react-google-recaptcha-v3/dist/useGoogleReCaptcha';
The recommended hook for functional components to programmatically execute reCAPTCHA validation. The `executeRecaptcha` function returned by the hook may be `undefined` until the script is loaded.
withGoogleReCaptcha
✓ import { withGoogleReCaptcha } from 'react-google-recaptcha-v3';
✗ import WithGoogleReCaptcha from 'react-google-recaptcha-v3/withGoogleReCaptcha';
A higher-order component (HOC) primarily for class components, injecting reCAPTCHA functionality via props. The documentation recommends `useGoogleReCaptcha` for functional components.
This quickstart demonstrates how to set up `GoogleReCaptchaProvider` and use the `useGoogleReCaptcha` hook to execute reCAPTCHA v3 verification upon form submission. It shows handling of loading states and the retrieved token, and highlights the necessity of providing a site key.
import React, { useState, useCallback, useEffect } from 'react';
import { GoogleReCaptchaProvider, useGoogleReCaptcha } from 'react-google-recaptcha-v3';
const RECAPTCHA_SITE_KEY = process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY ?? 'YOUR_SITE_KEY';
const RecaptchaForm = () => {
const { executeRecaptcha } = useGoogleReCaptcha();
const [token, setToken] = useState<string | null>(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
const handleReCaptchaVerify = useCallback(async () => {
setLoading(true);
setError(null);
if (!executeRecaptcha) {
setError('reCAPTCHA not loaded yet!');
setLoading(false);
return;
}
try {
const result = await executeRecaptcha('form_submission');
setToken(result);
console.log('reCAPTCHA token:', result);
// In a real application, send this token to your backend for verification
} catch (e) {
console.error('reCAPTCHA execution failed:', e);
setError('Failed to get reCAPTCHA token.');
} finally {
setLoading(false);
}
}, [executeRecaptcha]);
useEffect(() => {
// Optionally execute reCAPTCHA on component mount or a specific event
// handleReCaptchaVerify();
}, [handleReCaptchaVerify]);
return (
<div>
<h1>Contact Us</h1>
<form onSubmit={(e) => { e.preventDefault(); handleReCaptchaVerify(); }}>
{/* Your form fields here */}
<p>This form is protected by reCAPTCHA.</p>
<button type="submit" disabled={loading}>
{loading ? 'Verifying...' : 'Submit Form'}
</button>
{token && <p>Token received: {token.substring(0, 15)}...</p>}
{error && <p style={{ color: 'red' }}>Error: {error}</p>}
</form>
</div>
);
};
export default function App() {
if (!RECAPTCHA_SITE_KEY || RECAPTCHA_SITE_KEY === 'YOUR_SITE_KEY') {
console.error('Please provide a reCAPTCHA site key via NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable or directly in the code.');
return <div>Error: reCAPTCHA site key is missing.</div>;
}
return (
<GoogleReCaptchaProvider reCaptchaKey={RECAPTCHA_SITE_KEY} scriptProps={{ defer: true, async: true }}>
<RecaptchaForm />
</GoogleReCaptchaProvider>
);
}
Errors
Common errors & fixes
Error: reCAPTCHA has already been loaded on this page
This error typically occurs if the reCAPTCHA script is loaded multiple times, either by having more than one `GoogleReCaptchaProvider` or by manually including the reCAPTCHA script alongside the library.
fixEnsure there is only one `GoogleReCaptchaProvider` component in your application's React tree and remove any other `<script src="https://www.google.com/recaptcha/api.js..."></script>` tags from your HTML or component lifecycle methods.
TypeError: Cannot read properties of undefined (reading 'executeRecaptcha')
The `executeRecaptcha` function from `useGoogleReCaptcha` is `undefined` if the reCAPTCHA script has not finished loading, or if the hook is called outside the `GoogleReCaptchaProvider`'s context.
fixEnsure the component calling `useGoogleReCaptcha` is a descendant of `GoogleReCaptchaProvider`. Always check `if (executeRecaptcha)` before attempting to call it. You might also want to display a loading state until `executeRecaptcha` becomes available.
reCAPTCHA key is missing or invalid (often indicated by a console warning from Google reCAPTCHA itself)
The `reCaptchaKey` prop was not provided to `GoogleReCaptchaProvider` or the provided key is incorrect/malformed.
fixObtain a valid reCAPTCHA v3 site key from the Google reCAPTCHA admin console and pass it as the `reCaptchaKey` prop to `GoogleReCaptchaProvider`. Verify that the key is correctly formatted and corresponds to your registered domain.
Audit
Dependencies
reactrequiredPeer dependency for React applications, supporting versions 16.3 through 19.0.
react-domrequiredPeer dependency for rendering React components, supporting versions 17.0 through 19.0.
hoist-non-react-staticsrequiredRuntime dependency used internally, particularly by the `withGoogleReCaptcha` HOC to hoist static methods.