Skip to main content
The GoogleReCaptchaProvider component is a React Context provider that loads the Google ReCAPTCHA v3 script and makes the reCAPTCHA API available to all child components.
Place the GoogleReCaptchaProvider as high as possible in your React component tree to ensure you only have one instance of Google ReCAPTCHA per page.

​
Installation

npm install react-google-recaptcha-v3

​
Basic Usage

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider reCaptchaKey="YOUR_RECAPTCHA_SITE_KEY">
      <YourApp />
    </GoogleReCaptchaProvider>
  );
}

​
Props

​
reCaptchaKey
string
required
Your Google ReCAPTCHA v3 site key. You can obtain one from the Google ReCAPTCHA admin console.
​
children
ReactNode
required
The React components that should have access to the ReCAPTCHA context.
​
language
string
Optional language code for the ReCAPTCHA widget. See supported languages.Example: "en", "es", "fr", "de", etc.
​
useRecaptchaNet
boolean
default:"false"
Whether to load the script from recaptcha.net instead of google.com. This is useful for regions where google.com is blocked.See Google’s FAQ for more information.
​
useEnterprise
boolean
default:"false"
Enable Google ReCAPTCHA Enterprise. When enabled, you must create Enterprise keys (not standard v3 keys).
Enterprise keys are different from standard reCAPTCHA v3 keys. You must select “Scoring” as the integration type, which is equivalent to reCAPTCHA v3.
See the migration guide for more information.
​
scriptProps
object
Configuration options for the injected <script> tag.
​
scriptProps.nonce
string
Content Security Policy nonce for the script tag.
​
scriptProps.defer
boolean
default:"false"
Add the defer attribute to the script tag.
​
scriptProps.async
boolean
default:"false"
Add the async attribute to the script tag.
​
scriptProps.appendTo
'head' | 'body'
default:"'head'"
Where to append the script tag in the document.
​
scriptProps.id
string
default:"'google-recaptcha-v3'"
Custom ID for the script tag.
​
scriptProps.onLoadCallbackName
string
default:"'onRecaptchaLoadCallback'"
Custom name for the global onload callback function.
​
container
object
Configuration for rendering the reCAPTCHA badge in a custom container element.
​
container.element
string | HTMLElement
The ID of a DOM element or an HTMLElement reference where the reCAPTCHA badge should be rendered.If provided as a string, it will be used as both the container ID and a <div> with this ID will be created by the GoogleReCaptcha component.
​
container.parameters
object
Configuration parameters for the reCAPTCHA badge.
​
container.parameters.badge
'inline' | 'bottomleft' | 'bottomright'
Position of the reCAPTCHA badge. Use 'inline' to render it within the custom container.
​
container.parameters.theme
'dark' | 'light'
Theme for the reCAPTCHA badge.
​
container.parameters.tabindex
number
Tab index for the reCAPTCHA badge.
​
container.parameters.callback
() => void
Callback function executed when the user successfully completes the reCAPTCHA challenge.
​
container.parameters.expiredCallback
() => void
Callback function executed when the reCAPTCHA response expires.
​
container.parameters.errorCallback
() => void
Callback function executed when reCAPTCHA encounters an error.

​
Advanced Examples

​
With Custom Script Configuration

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_RECAPTCHA_SITE_KEY"
      scriptProps={{
        async: true,
        defer: true,
        appendTo: 'body',
        nonce: 'your-csp-nonce'
      }}
    >
      <YourApp />
    </GoogleReCaptchaProvider>
  );
}

​
With Language Support

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_RECAPTCHA_SITE_KEY"
      language="es" // Spanish
    >
      <YourApp />
    </GoogleReCaptchaProvider>
  );
}

​
With Custom Badge Container

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_RECAPTCHA_SITE_KEY"
      container={{
        element: 'recaptcha-badge',
        parameters: {
          badge: 'inline',
          theme: 'dark'
        }
      }}
    >
      <YourApp />
      {/* The badge will be rendered inside this div */}
      <div id="recaptcha-badge" />
    </GoogleReCaptchaProvider>
  );
}

​
With Enterprise Edition

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_ENTERPRISE_SITE_KEY"
      useEnterprise={true}
    >
      <YourApp />
    </GoogleReCaptchaProvider>
  );
}

​
Using recaptcha.net Domain

import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_RECAPTCHA_SITE_KEY"
      useRecaptchaNet={true}
    >
      <YourApp />
    </GoogleReCaptchaProvider>
  );
}

​
Best Practices

Single Provider Instance: Only use one GoogleReCaptchaProvider per page. Place it as high as possible in your component tree to avoid unnecessary re-initialization.
Framework Integration: When using with Next.js, place the provider in your _app.tsx file. For React Router, place it at the root of your routing configuration.
Script Loading: The provider automatically injects the Google ReCAPTCHA script. Do not manually add the script tag to your HTML.
Environment Variables: Store your reCAPTCHA site key in environment variables (e.g., NEXT_PUBLIC_RECAPTCHA_SITE_KEY) instead of hardcoding it.

​
Context Value

The provider makes the following values available through React Context:
  • executeRecaptcha: Function to execute reCAPTCHA validation (available after script loads)
  • container: The container element reference (if custom container is used)
These values can be accessed using the useGoogleReCaptcha hook or the withGoogleReCaptcha HOC.

​
Cleanup

The provider automatically cleans up when unmounted:
  • Removes the injected script tag
  • Removes the reCAPTCHA badge
  • Cleans up global window variables

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us