GoogleReCaptchaProvider - React Google reCAPTCHA V3

Overview

GoogleReCaptchaProvider is the root component that wraps your application (or a part of it) to initialize Google reCAPTCHA v3. It loads the reCAPTCHA script, manages the reCAPTCHA instance, and provides context to child components through React Context. Source: src/google-recaptcha-provider.tsx:63

Import

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

Props

reCaptchaKey

string

required

Your Google reCAPTCHA v3 site key. Get this from the Google reCAPTCHA Admin Console.

language

string

The language code for the reCAPTCHA widget (e.g., "en", "fr", "es"). If not specified, the user’s browser language will be used.

useRecaptchaNet

boolean

default:false

If true, loads the reCAPTCHA script from recaptcha.net instead of google.com. Useful for regions where google.com is blocked.

useEnterprise

boolean

default:false

If true, uses Google reCAPTCHA Enterprise instead of the standard version. Requires an Enterprise site key.

scriptProps

object

Configuration options for the script tag that loads reCAPTCHA.

Show scriptProps properties

scriptProps.nonce

string

Content Security Policy nonce for the script tag.

scriptProps.defer

boolean

default:false

If true, adds the defer attribute to the script tag.

scriptProps.async

boolean

default:false

If true, adds the async attribute to the script tag.

scriptProps.appendTo

'head' | 'body'

default:"head"

Where to append the script tag in the DOM.

scriptProps.id

string

default:"google-recaptcha-v3"

Custom ID for the script tag.

scriptProps.onLoadCallbackName

string

default:"onRecaptchaLoadCallback"

Name of the global callback function called when reCAPTCHA loads (used with explicit rendering).

container

object

Configuration for explicit rendering mode. When provided, reCAPTCHA will render into a specific container element.

Show container properties

container.element

string | HTMLElement

The container element where reCAPTCHA should render. Can be a DOM element or element ID string.

container.parameters

object

required

Rendering parameters for the reCAPTCHA widget.

Show parameters properties

container.parameters.badge

'inline' | 'bottomleft' | 'bottomright'

default:"inline"

Position of the reCAPTCHA badge.

container.parameters.theme

'dark' | 'light'

Color theme of the reCAPTCHA badge.

container.parameters.tabindex

number

Tab index for keyboard navigation.

container.parameters.callback

() => void

Callback executed when the user successfully completes a challenge.

container.parameters.expiredCallback

() => void

Callback executed when the reCAPTCHA response expires.

container.parameters.errorCallback

() => void

Callback executed when reCAPTCHA encounters an error.

children

ReactNode

required

The child components that will have access to the reCAPTCHA context.

Context Value

The provider creates a context with the following value (accessible via useGoogleReCaptcha or GoogleReCaptchaConsumer):

executeRecaptcha

(action?: string) => Promise<string> | undefined

Function to execute reCAPTCHA and get a token. Returns undefined until reCAPTCHA is fully loaded.

action: Optional string describing the action being performed (e.g., "login", "submit_form")
Returns: Promise that resolves to the reCAPTCHA token
Throws: Error if reCAPTCHA is not loaded when called

container

string | HTMLElement | undefined

The container element used for explicit rendering, if provided.

Usage Examples

Basic Usage

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

function App() {
  return (
    <GoogleReCaptchaProvider reCaptchaKey="YOUR_SITE_KEY">
      <YourComponents />
    </GoogleReCaptchaProvider>
  );
}

With Language and Custom Script Props

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

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

Using reCAPTCHA Enterprise

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

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

Using recaptcha.net Domain

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

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

Explicit Rendering with Custom Container

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

function App() {
  return (
    <GoogleReCaptchaProvider
      reCaptchaKey="YOUR_SITE_KEY"
      container={{
        element: 'recaptcha-container',
        parameters: {
          badge: 'inline',
          theme: 'dark',
          callback: () => console.log('Challenge completed'),
          expiredCallback: () => console.log('Challenge expired'),
          errorCallback: () => console.log('Challenge error')
        }
      }}
    >
      <div id="recaptcha-container" />
      <YourComponents />
    </GoogleReCaptchaProvider>
  );
}

Consumer

The provider also exports GoogleReCaptchaConsumer for consuming the context in class components:

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

class MyComponent extends React.Component {
  render() {
    return (
      <GoogleReCaptchaConsumer>
        {({ executeRecaptcha }) => (
          <button
            onClick={async () => {
              if (!executeRecaptcha) return;
              const token = await executeRecaptcha('button_click');
              console.log(token);
            }}
          >
            Click me
          </button>
        )}
      </GoogleReCaptchaConsumer>
    );
  }
}

TypeScript Interfaces

See TypeScript Interfaces for complete type definitions.

Cleanup

The provider automatically cleans up when unmounted:

Removes the reCAPTCHA script tag
Removes the reCAPTCHA badge from the DOM
Clears internal reCAPTCHA configuration

useGoogleReCaptcha - Hook to access the reCAPTCHA context
GoogleReCaptcha - Component for automatic token generation
withGoogleReCaptcha - HOC for class components
TypeScript Interfaces - Type definitions

Components

TypeScript

​Overview

​Import

​Props

​Context Value

​Usage Examples

​Basic Usage

​With Language and Custom Script Props

​Using reCAPTCHA Enterprise

​Using recaptcha.net Domain

​Explicit Rendering with Custom Container

​Consumer

​TypeScript Interfaces

​Cleanup

​Related APIs

Build docs developers (and LLMs) love

Overview

Import

Props

Context Value

Usage Examples

Basic Usage

With Language and Custom Script Props

Using reCAPTCHA Enterprise

Using recaptcha.net Domain

Explicit Rendering with Custom Container

Consumer

TypeScript Interfaces

Cleanup

Related APIs