{"id":15782,"library":"react-google-recaptcha-v3","title":"React Google reCAPTCHA v3 Integration","description":"react-google-recaptcha-v3 is a React library that simplifies the integration of Google reCAPTCHA v3 into web applications. It provides a `GoogleReCaptchaProvider` component to manage the reCAPTCHA script loading and context, along with a `useGoogleReCaptcha` hook and a `withGoogleReCaptcha` HOC for executing reCAPTCHA validation programmatically. The library is currently at version 1.11.0 and maintains an active release cadence with regular updates and fixes. It differentiates itself by offering flexible script injection control via `scriptProps` and explicit support for Google reCAPTCHA Enterprise, requiring specific key types and 'Scoring' integration. This library focuses on an invisible reCAPTCHA experience, providing a score to differentiate human from bot interactions without interrupting the user flow.","status":"active","version":"1.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/t49tran/react-google-recaptcha-v3","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-google-recaptcha-v3","lang":"bash","label":"npm"},{"cmd":"yarn add react-google-recaptcha-v3","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-google-recaptcha-v3","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React applications, supporting versions 16.3 through 19.0.","package":"react","optional":false},{"reason":"Peer dependency for rendering React components, supporting versions 17.0 through 19.0.","package":"react-dom","optional":false},{"reason":"Runtime dependency used internally, particularly by the `withGoogleReCaptcha` HOC to hoist static methods.","package":"hoist-non-react-statics","optional":false}],"imports":[{"note":"This component should wrap your application or relevant parts to provide reCAPTCHA context. Place it high in the component tree to avoid reloads.","wrong":"const { GoogleReCaptchaProvider } = require('react-google-recaptcha-v3');","symbol":"GoogleReCaptchaProvider","correct":"import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';"},{"note":"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.","wrong":"import useGoogleReCaptcha from 'react-google-recaptcha-v3/dist/useGoogleReCaptcha';","symbol":"useGoogleReCaptcha","correct":"import { useGoogleReCaptcha } from 'react-google-recaptcha-v3';"},{"note":"A higher-order component (HOC) primarily for class components, injecting reCAPTCHA functionality via props. The documentation recommends `useGoogleReCaptcha` for functional components.","wrong":"import WithGoogleReCaptcha from 'react-google-recaptcha-v3/withGoogleReCaptcha';","symbol":"withGoogleReCaptcha","correct":"import { withGoogleReCaptcha } from 'react-google-recaptcha-v3';"}],"quickstart":{"code":"import React, { useState, useCallback, useEffect } from 'react';\nimport { GoogleReCaptchaProvider, useGoogleReCaptcha } from 'react-google-recaptcha-v3';\n\nconst RECAPTCHA_SITE_KEY = process.env.NEXT_PUBLIC_RECAPTCHA_SITE_KEY ?? 'YOUR_SITE_KEY';\n\nconst RecaptchaForm = () => {\n  const { executeRecaptcha } = useGoogleReCaptcha();\n  const [token, setToken] = useState<string | null>(null);\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n\n  const handleReCaptchaVerify = useCallback(async () => {\n    setLoading(true);\n    setError(null);\n    if (!executeRecaptcha) {\n      setError('reCAPTCHA not loaded yet!');\n      setLoading(false);\n      return;\n    }\n\n    try {\n      const result = await executeRecaptcha('form_submission');\n      setToken(result);\n      console.log('reCAPTCHA token:', result);\n      // In a real application, send this token to your backend for verification\n    } catch (e) {\n      console.error('reCAPTCHA execution failed:', e);\n      setError('Failed to get reCAPTCHA token.');\n    } finally {\n      setLoading(false);\n    }\n  }, [executeRecaptcha]);\n\n  useEffect(() => {\n    // Optionally execute reCAPTCHA on component mount or a specific event\n    // handleReCaptchaVerify(); \n  }, [handleReCaptchaVerify]);\n\n  return (\n    <div>\n      <h1>Contact Us</h1>\n      <form onSubmit={(e) => { e.preventDefault(); handleReCaptchaVerify(); }}>\n        {/* Your form fields here */}\n        <p>This form is protected by reCAPTCHA.</p>\n        <button type=\"submit\" disabled={loading}>\n          {loading ? 'Verifying...' : 'Submit Form'}\n        </button>\n        {token && <p>Token received: {token.substring(0, 15)}...</p>}\n        {error && <p style={{ color: 'red' }}>Error: {error}</p>}\n      </form>\n    </div>\n  );\n};\n\nexport default function App() {\n  if (!RECAPTCHA_SITE_KEY || RECAPTCHA_SITE_KEY === 'YOUR_SITE_KEY') {\n    console.error('Please provide a reCAPTCHA site key via NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable or directly in the code.');\n    return <div>Error: reCAPTCHA site key is missing.</div>;\n  }\n  return (\n    <GoogleReCaptchaProvider reCaptchaKey={RECAPTCHA_SITE_KEY} scriptProps={{ defer: true, async: true }}>\n      <RecaptchaForm />\n    </GoogleReCaptchaProvider>\n  );\n}\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Migrate direct script-related props to the `scriptProps` object. For example, change `<GoogleReCaptchaProvider nonce='abc'>` to `<GoogleReCaptchaProvider scriptProps={{ nonce: 'abc' }}>`.","message":"In v1.7.0, the `nonce`, `async`, and `defer` props directly on `GoogleReCaptchaProvider` were grouped into a single `scriptProps` object. Existing direct usages will no longer function as expected.","severity":"breaking","affected_versions":">=1.7.0"},{"fix":"Generate new reCAPTCHA Enterprise keys via the Google Cloud Console, ensure 'Scoring' integration is selected, and pass `useEnterprise={true}` to `GoogleReCaptchaProvider`.","message":"When integrating Google reCAPTCHA Enterprise, you MUST create new site keys specifically for Enterprise and select 'Scoring' as the integration type. Standard reCAPTCHA v3 keys will not work with the `useEnterprise` prop enabled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `GoogleReCaptchaProvider` is placed as high as possible in your React component tree, typically at the root of your application, to ensure a single, consistent reCAPTCHA instance.","message":"Placing multiple `GoogleReCaptchaProvider` instances in your application or placing it low in the component tree can lead to performance issues, unnecessary script reloads, or reCAPTCHA conflicts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new development and functional components, prefer using the `useGoogleReCaptcha` hook. Refactor existing class components to use the hook if migrating to functional components.","message":"The `withGoogleReCaptcha` Higher-Order Component (HOC) is primarily for class components. While still supported, the `useGoogleReCaptcha` hook is the recommended and more idiomatic approach for functional components. The HOC may be considered for removal in future major versions.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure 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.","cause":"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.","error":"Error: reCAPTCHA has already been loaded on this page"},{"fix":"Ensure 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'executeRecaptcha')"},{"fix":"Obtain 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.","cause":"The `reCaptchaKey` prop was not provided to `GoogleReCaptchaProvider` or the provided key is incorrect/malformed.","error":"reCAPTCHA key is missing or invalid (often indicated by a console warning from Google reCAPTCHA itself)"}],"ecosystem":"npm"}