Package installation
Install the library using your preferred package manager:
npm install react-google-recaptcha-v3
Peer dependencies
The library requires React and React DOM as peer dependencies. Make sure you have compatible versions installed:
{
"dependencies": {
"react": "^16.3 || ^17.0 || ^18.0 || ^19.0",
"react-dom": "^17.0 || ^18.0 || ^19.0"
}
}
The library supports React 16.3+ (for Context API support), React 17, React 18, and React 19.
Get a reCAPTCHA key
Before you can use the library, you need to obtain a site key from Google:
Visit the reCAPTCHA admin console
Register a new site
Click the + button to create a new site key.
Configure your site
- Label: Give your site a descriptive name
- reCAPTCHA type: Select reCAPTCHA v3
- Domains: Add your domain(s). For development, include
localhost
- Accept the reCAPTCHA Terms of Service
Copy your keys
After registration, you’ll receive:
- Site key - Use this in your React app (client-side)
- Secret key - Use this on your backend for verification (never expose this client-side)
Never commit your secret key to version control or expose it in client-side code. Only use the site key in your React application.
Environment variables (recommended)
Store your reCAPTCHA site key in environment variables for better security and configuration management:
REACT_APP_RECAPTCHA_SITE_KEY=your_site_key_here
# or for Vite
VITE_RECAPTCHA_SITE_KEY=your_site_key_here
Environment variables must be prefixed with:
REACT_APP_ for Create React AppVITE_ for ViteNEXT_PUBLIC_ for Next.js
This makes them available in the browser. TypeScript support
The library includes TypeScript type definitions out of the box. No additional @types package is needed.
import {
GoogleReCaptchaProvider,
useGoogleReCaptcha
} from 'react-google-recaptcha-v3';
// Types are automatically available
const { executeRecaptcha } = useGoogleReCaptcha();
Verification
Verify your installation by importing the provider:
import { GoogleReCaptchaProvider } from 'react-google-recaptcha-v3';
function App() {
return (
<GoogleReCaptchaProvider reCaptchaKey="your-site-key">
<div>Your app content</div>
</GoogleReCaptchaProvider>
);
}
export default App;
Next steps
Now that you have the library installed and your reCAPTCHA key ready, continue to the quickstart guide to implement your first reCAPTCHA validation.