TypeScript Interfaces - React Google reCAPTCHA V3

Overview

This page documents all TypeScript interfaces and types available in react-google-recaptcha-v3, including both exported interfaces and component prop interfaces that can be inferred from component usage.

Exported Interfaces

These interfaces are explicitly exported and can be imported directly from the package.

Provider Interfaces

IGoogleReCaptchaProviderProps

Props interface for the GoogleReCaptchaProvider component.

This interface is not exported from the package. TypeScript will infer the prop types automatically when using the component. If you need to reference these types explicitly, you can use React.ComponentProps<typeof GoogleReCaptchaProvider>.

Source: src/google-recaptcha-provider.tsx:20

interface IGoogleReCaptchaProviderProps {
  reCaptchaKey: string;
  language?: string;
  useRecaptchaNet?: boolean;
  useEnterprise?: boolean;
  scriptProps?: {
    nonce?: string;
    defer?: boolean;
    async?: boolean;
    appendTo?: 'head' | 'body';
    id?: string;
    onLoadCallbackName?: string;
  };
  container?: {
    element?: string | HTMLElement;
    parameters: {
      badge?: 'inline' | 'bottomleft' | 'bottomright';
      theme?: 'dark' | 'light';
      tabindex?: number;
      callback?: () => void;
      expiredCallback?: () => void;
      errorCallback?: () => void;
    }
  };
  children: ReactNode;
}

reCaptchaKey

string

required

Google reCAPTCHA v3 site key

language

string

Language code (e.g., “en”, “fr”, “es”)

useRecaptchaNet

boolean

Use recaptcha.net domain instead of google.com

useEnterprise

boolean

Use Google reCAPTCHA Enterprise

scriptProps

object

Script tag configuration options

container

object

Explicit rendering container configuration

children

ReactNode

required

Child components

IGoogleReCaptchaConsumerProps

Context value provided by GoogleReCaptchaProvider and consumed by hooks/HOCs.

This interface is exported and can be imported from react-google-recaptcha-v3.

Source: src/google-recaptcha-provider.tsx:47

export interface IGoogleReCaptchaConsumerProps {
  executeRecaptcha?: (action?: string) => Promise<string>;
  container?: string | HTMLElement;
}

executeRecaptcha

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

Function to execute reCAPTCHA and get a token. Undefined until loaded.

container

string | HTMLElement | undefined

Container element for explicit rendering

Component Prop Interfaces

IGoogleRecaptchaProps

Props interface for the GoogleReCaptcha component.

This interface is exported and can be imported from react-google-recaptcha-v3.

Source: src/google-recaptcha.tsx:5

export interface IGoogleRecaptchaProps {
  onVerify: (token: string) => void | Promise<void>;
  action?: string;
  refreshReCaptcha?: boolean | string | number | null;
}

onVerify

(token: string) => void | Promise<void>

required

Callback that receives the reCAPTCHA token

action

string

Action name for this verification

refreshReCaptcha

boolean | string | number | null

Trigger to refresh and re-execute reCAPTCHA

IWithGoogleReCaptchaProps

Props interface injected by the withGoogleReCaptcha HOC.

This interface is exported and can be imported from react-google-recaptcha-v3.

Source: src/with-google-recaptcha.tsx:9

export interface IWithGoogleReCaptchaProps {
  googleReCaptchaProps: IGoogleReCaptchaConsumerProps;
}

googleReCaptchaProps

IGoogleReCaptchaConsumerProps

required

Object containing executeRecaptcha function and container info

Additional Exports

GoogleReCaptchaContext

The React Context object that stores the reCAPTCHA state. Exported for advanced use cases.

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

// Advanced: Manually consume the context
function MyComponent() {
  const context = React.useContext(GoogleReCaptchaContext);
  // Use context.executeRecaptcha
}

In most cases, use the useGoogleReCaptcha hook instead of consuming the context directly.

GoogleReCaptchaConsumer

The React Context Consumer component for class-based components. See GoogleReCaptchaProvider API for usage.

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

class MyComponent extends React.Component {
  render() {
    return (
      <GoogleReCaptchaConsumer>
        {({ executeRecaptcha }) => (
          <button onClick={() => executeRecaptcha?.('action')}>
            Verify
          </button>
        )}
      </GoogleReCaptchaConsumer>
    );
  }
}

Usage Examples

Typing Provider Props

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

// Use React.ComponentProps to extract prop types
type ProviderProps = React.ComponentProps<typeof GoogleReCaptchaProvider>;

const providerProps: ProviderProps = {
  reCaptchaKey: 'YOUR_SITE_KEY',
  language: 'en',
  useRecaptchaNet: false,
  useEnterprise: false,
  scriptProps: {
    async: true,
    defer: true,
    appendTo: 'head',
    nonce: 'random-nonce'
  },
  children: <div>My App</div>
};

function App() {
  return <GoogleReCaptchaProvider {...providerProps} />;
}

Typing Hook Return Value

import { useGoogleReCaptcha, IGoogleReCaptchaConsumerProps } from 'react-google-recaptcha-v3';

function MyComponent() {
  const recaptcha: IGoogleReCaptchaConsumerProps = useGoogleReCaptcha();
  
  const handleAction = async () => {
    if (!recaptcha.executeRecaptcha) {
      console.log('Not ready');
      return;
    }
    
    const token: string = await recaptcha.executeRecaptcha('my_action');
    console.log(token);
  };
  
  return <button onClick={handleAction}>Click me</button>;
}

Typing Component Props

import { GoogleReCaptcha, IGoogleRecaptchaProps } from 'react-google-recaptcha-v3';

const componentProps: IGoogleRecaptchaProps = {
  onVerify: (token: string) => {
    console.log('Token:', token);
  },
  action: 'page_load',
  refreshReCaptcha: true
};

function App() {
  return <GoogleReCaptcha {...componentProps} />;
}

Typing HOC-Wrapped Components

import React, { Component } from 'react';
import {
  withGoogleReCaptcha,
  IWithGoogleReCaptchaProps
} from 'react-google-recaptcha-v3';

interface OwnProps {
  userId: string;
  userName: string;
}

// Combine your props with the HOC props
type Props = OwnProps & IWithGoogleReCaptchaProps;

class UserProfile extends Component<Props> {
  handleSubmit = async () => {
    const { executeRecaptcha } = this.props.googleReCaptchaProps;
    
    if (!executeRecaptcha) return;
    
    const token: string = await executeRecaptcha('profile_update');
    console.log('Token for user', this.props.userId, ':', token);
  };
  
  render() {
    return (
      <div>
        <h1>{this.props.userName}</h1>
        <button onClick={this.handleSubmit}>Update</button>
      </div>
    );
  }
}

export default withGoogleReCaptcha(UserProfile);

Typing Custom Hooks

import { useCallback } from 'react';
import {
  useGoogleReCaptcha,
  IGoogleReCaptchaConsumerProps
} from 'react-google-recaptcha-v3';

interface VerificationResult {
  success: boolean;
  score: number;
  action: string;
}

interface UseRecaptchaVerify {
  verify: (action: string) => Promise<VerificationResult>;
  isReady: boolean;
}

function useRecaptchaVerify(): UseRecaptchaVerify {
  const { executeRecaptcha }: IGoogleReCaptchaConsumerProps = useGoogleReCaptcha();
  
  const verify = useCallback(
    async (action: string): Promise<VerificationResult> => {
      if (!executeRecaptcha) {
        throw new Error('reCAPTCHA not ready');
      }
      
      const token: string = await executeRecaptcha(action);
      
      const response = await fetch('/api/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token, action })
      });
      
      return response.json() as Promise<VerificationResult>;
    },
    [executeRecaptcha]
  );
  
  return {
    verify,
    isReady: !!executeRecaptcha
  };
}

Typing Callback Functions

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

// Synchronous callback
const handleVerifySync: IGoogleRecaptchaProps['onVerify'] = (token) => {
  console.log('Token:', token);
};

// Asynchronous callback
const handleVerifyAsync: IGoogleRecaptchaProps['onVerify'] = async (token) => {
  await fetch('/api/verify', {
    method: 'POST',
    body: JSON.stringify({ token })
  });
};

Typing Container Configuration

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

// Extract container type from component props
type ProviderProps = React.ComponentProps<typeof GoogleReCaptchaProvider>;
type ContainerConfig = ProviderProps['container'];

const containerConfig: ContainerConfig = {
  element: 'recaptcha-badge',
  parameters: {
    badge: 'inline',
    theme: 'dark',
    tabindex: 0,
    callback: () => console.log('Success'),
    expiredCallback: () => console.log('Expired'),
    errorCallback: () => console.log('Error')
  }
};

Typing Script Props

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

// Extract scriptProps type from component props
type ProviderProps = React.ComponentProps<typeof GoogleReCaptchaProvider>;
type ScriptProps = ProviderProps['scriptProps'];

const scriptConfig: ScriptProps = {
  nonce: 'abc123',
  defer: true,
  async: true,
  appendTo: 'body',
  id: 'my-recaptcha-script',
  onLoadCallbackName: 'myCustomCallback'
};

Utility Types

You can create custom utility types based on the exported interfaces:

import {
  IGoogleReCaptchaConsumerProps,
  IGoogleRecaptchaProps
} from 'react-google-recaptcha-v3';

// Extract the executeRecaptcha function type
type ExecuteRecaptcha = NonNullable<IGoogleReCaptchaConsumerProps['executeRecaptcha']>;

// Extract the onVerify callback type
type VerifyCallback = IGoogleRecaptchaProps['onVerify'];

// Create a type for async verify functions
type AsyncVerifyCallback = (token: string) => Promise<void>;

// Type guard for checking if executeRecaptcha is available
function hasExecuteRecaptcha(
  props: IGoogleReCaptchaConsumerProps
): props is IGoogleReCaptchaConsumerProps & { executeRecaptcha: ExecuteRecaptcha } {
  return props.executeRecaptcha !== undefined;
}

Generic Type Parameters

withGoogleReCaptcha with Custom Props

import { ComponentType } from 'react';
import { withGoogleReCaptcha, IWithGoogleReCaptchaProps } from 'react-google-recaptcha-v3';

interface MyComponentProps {
  title: string;
  count: number;
}

const MyComponent: ComponentType<MyComponentProps & Partial<IWithGoogleReCaptchaProps>> = ({
  title,
  count,
  googleReCaptchaProps
}) => {
  return (
    <div>
      <h1>{title}</h1>
      <p>Count: {count}</p>
      <p>reCAPTCHA ready: {googleReCaptchaProps?.executeRecaptcha ? 'Yes' : 'No'}</p>
    </div>
  );
};

const WrappedComponent = withGoogleReCaptcha(MyComponent);

// Usage maintains original props
<WrappedComponent title="Hello" count={42} />

Internal Types (Not Exported)

These types are used internally but not exported. They’re documented here for completeness:

GoogleRecaptchaError

Source: src/google-recaptcha-provider.tsx:16

enum GoogleRecaptchaError {
  SCRIPT_NOT_AVAILABLE = 'Recaptcha script is not available'
}

IInjectGoogleReCaptchaScriptParams

Source: src/utils.ts:1

interface IInjectGoogleReCaptchaScriptParams {
  render: string;
  onLoadCallbackName: string;
  useRecaptchaNet: boolean;
  useEnterprise: boolean;
  onLoad: () => void;
  onError: () => void;
  language?: string;
  scriptProps?: {
    nonce?: string;
    defer?: boolean;
    async?: boolean;
    appendTo?: 'head' | 'body';
    id?: string;
  };
}

Type Compatibility

All interfaces are compatible with React 16.8+ and TypeScript 3.7+.

React Types

import { ReactNode } from 'react';

// IGoogleReCaptchaProviderProps uses ReactNode for children
const children: ReactNode = <div>Hello</div>;

Promise Types

// executeRecaptcha returns a Promise<string>
const token: Promise<string> = executeRecaptcha('action');

// onVerify can return void or Promise<void>
const callback1: (token: string) => void = (token) => {};
const callback2: (token: string) => Promise<void> = async (token) => {};

GoogleReCaptchaProvider - Provider component
GoogleReCaptcha - Automatic verification component
useGoogleReCaptcha - Hook for functional components
withGoogleReCaptcha - HOC for class components

Components

TypeScript

​Overview

​Exported Interfaces

​Provider Interfaces

​IGoogleReCaptchaProviderProps

​IGoogleReCaptchaConsumerProps

​Component Prop Interfaces

​IGoogleRecaptchaProps

​IWithGoogleReCaptchaProps

​Additional Exports

​GoogleReCaptchaContext

​GoogleReCaptchaConsumer

​Usage Examples

​Typing Provider Props

​Typing Hook Return Value

​Typing Component Props

​Typing HOC-Wrapped Components

​Typing Custom Hooks

​Typing Callback Functions

​Typing Container Configuration

​Typing Script Props

​Utility Types

​Generic Type Parameters

​withGoogleReCaptcha with Custom Props

​Internal Types (Not Exported)

​GoogleRecaptchaError

​IInjectGoogleReCaptchaScriptParams

​Type Compatibility

​React Types

​Promise Types

​Related APIs

Build docs developers (and LLMs) love

Overview

Exported Interfaces

Provider Interfaces

IGoogleReCaptchaProviderProps

IGoogleReCaptchaConsumerProps

Component Prop Interfaces

IGoogleRecaptchaProps

IWithGoogleReCaptchaProps

Additional Exports

GoogleReCaptchaContext

GoogleReCaptchaConsumer

Usage Examples

Typing Provider Props

Typing Hook Return Value

Typing Component Props

Typing HOC-Wrapped Components

Typing Custom Hooks

Typing Callback Functions

Typing Container Configuration

Typing Script Props

Utility Types

Generic Type Parameters

withGoogleReCaptcha with Custom Props

Internal Types (Not Exported)

GoogleRecaptchaError

IInjectGoogleReCaptchaScriptParams

Type Compatibility

React Types

Promise Types

Related APIs