next-recaptcha-v3

To use ReCaptcha, wrap your application with ReCaptchaProvider. This component uses next/script to load the ReCaptcha script into your document.

You can provide your site key in two ways:

1. Set the NEXT_PUBLIC_RECAPTCHA_SITE_KEY environment variable.
2. Pass the reCaptchaKey prop directly to ReCaptchaProvider.

import { ReCaptchaProvider } from "next-recaptcha-v3";

const MyApp = ({ Component, pageProps }) => (
  <ReCaptchaProvider reCaptchaKey="[GTM-XXXXXXX]">
    <Component {...pageProps} />
  </ReCaptchaProvider>
);

Install the package using your preferred package manager. Note that this is a pure ESM package and cannot be require()'d from CommonJS.

npm i next-recaptcha-v3
# or
pnpm i next-recaptcha-v3
# or
yarn add next-recaptcha-v3

The reCAPTCHA library is exposed via a global grecaptcha object. This object provides access to standard reCAPTCHA functionality and, if using reCAPTCHA Enterprise, an enterprise property.

// Standard reCAPTCHA
grecaptcha.render(...);

// reCAPTCHA Enterprise
grecaptcha.enterprise.render(...);

The withReCaptcha HOC injects ReCaptcha context props directly into your component. This is useful when you want to avoid using hooks inside the component body or when working with class components.

import { useEffect, useState } from "react";
import { withReCaptcha, WithReCaptchaProps } from "next-recaptcha-v3";

interface MyPageProps extends WithReCaptchaProps {}

const MyPage: React.FC<MyPageProps> = ({ isLoaded, executeRecaptcha }) => {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    if (isLoaded) {
      const generateToken = async () => {
        const newToken = await executeRecaptcha("page_view");
        setToken(newToken);
      };
      generateToken();
    }
  }, [isLoaded, executeRecaptcha]);

  return <h1 onClick={() => console.log(token)}>Hello</h1>;
};

export default withReCaptcha(MyPage);

You can use the <ReCaptcha /> component to trigger token generation via an onValidate callback. This is useful for declarative token management.

import { useEffect, useState } from "react";
import { ReCaptcha } from "next-recaptcha-v3";

const MyPage = () => {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    if (token) {
      // Perform server-side validation logic here
      console.log("Token generated:", token);
    }
  }, [token]);

  return (
    <>
      <ReCaptcha onValidate={setToken} action="page_view" />
      <h1>Hello</h1>
    </>
  );
};

The useReCaptcha hook is the recommended way to access the ReCaptcha context. It provides access to the global grecaptcha object, the loading state, and the executeRecaptcha function used to generate tokens.

Returned properties:

• reCaptchaKey: The site key being used.
• grecaptcha: The global ReCaptcha object.
• isLoaded: true if the ReCaptcha script has been loaded.
• isError: true if an error occurred during loading.
• error: The error object if loading failed.
• executeRecaptcha: A function to generate a one-time token. It accepts an action name (alphanumeric, slashes, and underscores only; must not be user-specific).

import { useReCaptcha } from "next-recaptcha-v3";

const { 
  reCaptchaKey, 
  grecaptcha, 
  isLoaded, 
  isError, 
  error, 
  executeRecaptcha 
} = useReCaptcha();

The ReCaptchaProvider component accepts the following props:

All extra props are passed directly to the underlying next/script component.

The useReCaptcha hook provides access to the reCAPTCHA instance within functional components. It returns an object containing the execute method, which you can call to trigger a reCAPTCHA verification and receive a token.

import { useReCaptcha } from 'next-recaptcha-v3';

const MyComponent = () => {
  const { execute } = useReCaptcha();

  const handleAction = async (actionName: string) => {
    const token = await execute(actionName);
    // Send token to your server for verification
  };

  return <button onClick={() => handleAction('login')}>Verify</button>;
};