Skip to main content

​
Install the Package

Install react-google-recaptcha using your preferred package manager: 
npm install --save react-google-recaptcha

​
Peer Dependencies

The library requires React as a peer dependency. Make sure you have React installed in your project:
Minimum React Version: react-google-recaptcha requires React >=16.4.1
If you don’t have React installed yet: 
npm install react react-dom

​
Get Your reCAPTCHA Site Key

Before you can use reCAPTCHA in your application, you need to register your site with Google and obtain API keys.
1

Visit the reCAPTCHA Admin Console

Go to http://www.google.com/recaptcha/admin and sign in with your Google account.
2

Register a New Site

Click the + button to register a new site:
  • Label: A descriptive name for your site
  • reCAPTCHA type: Select reCAPTCHA v2
  • Choose your preferred challenge type:
    • “I’m not a robot” Checkbox (most common)
    • Invisible reCAPTCHA badge (programmatic)
3

Add Your Domains

Enter the domains where your application will be hosted:
  • For development: localhost
  • For production: Your actual domain (e.g., example.com)
You can add multiple domains to the same site key, including both development and production domains.
4

Copy Your Site Key

After registration, you’ll receive two keys:
  • Site key: Used in your frontend React application (this is what you need)
  • Secret key: Used on your backend server for verification
Never expose your Secret key in frontend code. It should only be used on your backend server.

​
Project Setup

Once you have your site key, you’re ready to integrate reCAPTCHA into your React application.

​
Basic Setup

Import the component in your React file: 
import ReCAPTCHA from "react-google-recaptcha";
Store your site key in environment variables for better security and configuration management:
.env
REACT_APP_RECAPTCHA_SITE_KEY=your_site_key_here
Then use it in your component: 
import ReCAPTCHA from "react-google-recaptcha";

function MyForm() {
  return (
    <ReCAPTCHA
      sitekey={process.env.REACT_APP_RECAPTCHA_SITE_KEY}
      onChange={(value) => console.log("Captcha value:", value)}
    />
  );
}
The environment variable prefix depends on your build tool:
  • Create React App: REACT_APP_
  • Vite: VITE_
  • Next.js: NEXT_PUBLIC_

​
Advanced Configuration

​
Using recaptcha.net

If google.com is blocked in your region, configure the library to use recaptcha.net instead: 
// Add this before rendering your React app
window.recaptchaOptions = {
  useRecaptchaNet: true,
};

​
Google reCAPTCHA Enterprise

To use Google reCAPTCHA Enterprise instead of the free version: 
window.recaptchaOptions = {
  enterprise: true,
};

​
CSP Nonce Support

For applications with Content Security Policy (CSP), you can provide a nonce: 
window.recaptchaOptions = {
  nonce: document.querySelector('meta[name="csp-nonce"]').getAttribute('content'),
};
Set window.recaptchaOptions in your HTML file or at the top of your application entry point, before React renders.

​
Verification

You can verify your installation is working by checking if the component renders without errors. We’ll build a complete example in the next section.

Next: Quick Start

Learn how to build your first reCAPTCHA-protected form with complete examples

Build docs developers (and LLMs) love

Get started for freeTalk to us