use-google-recaptcha

A React hook for Google reCAPTCHA v3 integration with TypeScript support.

Features

• 🔐 Google reCAPTCHA v3 integration
• ⚛️ React Hook - Easy to use in functional components
• 📝 TypeScript - Full type safety
• 🎯 Lightweight - Minimal dependencies
• 🚀 Modern - Uses latest React patterns
• 🔧 Flexible - Customizable options and actions

Installation

# npm
npm install use-google-recaptcha

# yarn
yarn add use-google-recaptcha

# pnpm
pnpm add use-google-recaptcha

Prerequisites

Before using this hook, you need to:

1. Register your site at Google reCAPTCHA Admin Console
2. Get your site key for reCAPTCHA v3
3. Add your domain to the reCAPTCHA configuration

Usage

Basic Usage

import React from 'react';
import { useGoogleReCaptcha } from 'use-google-recaptcha';

function MyComponent() {
  const { execute, executing } = useGoogleReCaptcha({
    key: 'your-recaptcha-site-key'
  });

  const handleSubmit = async () => {
    try {
      const token = await execute('submit');
      console.log('reCAPTCHA token:', token);
      
      // Send token to your backend for verification
      // const response = await fetch('/api/verify-recaptcha', {
      //   method: 'POST',
      //   body: JSON.stringify({ token }),
      //   headers: { 'Content-Type': 'application/json' }
      // });
    } catch (error) {
      console.error('reCAPTCHA error:', error);
    }
  };

  return (
    <div>
      <button 
        onClick={handleSubmit} 
        disabled={executing}
      >
        {executing ? 'Verifying...' : 'Submit'}
      </button>
    </div>
  );
}

Using Environment Variables

You can also use environment variables to store your reCAPTCHA site key:

// .env.local (Next.js)
NEXT_PUBLIC_RECAPTHA_SITE_KEY=your-site-key

// .env (Create React App)
REACT_APP_RECAPTHA_SITE_KEY=your-site-key

import { useGoogleReCaptcha } from 'use-google-recaptcha';

function MyComponent() {
  // The hook will automatically use the environment variable
  const { execute, executing } = useGoogleReCaptcha();
  
  // ... rest of your component
}

API Reference

useGoogleReCaptcha(options?)

Parameters

• options (optional): Configuration object
  • key?: string - Your reCAPTCHA site key. If not provided, will use environment variables
  • nonce?: string - Optional nonce for Content Security Policy

Returns

An object with the following properties:

• execute: (action?: string) => Promise<string> - Function to execute reCAPTCHA
• executing: boolean - Whether reCAPTCHA is currently executing

Actions

The execute function accepts an optional action parameter that helps you analyze different user interactions:

await execute('login');    // For login forms
await execute('contact');  // For contact forms
await execute('purchase'); // For purchase flows
await execute('search');   // For search functionality

Environment Variables

The hook supports the following environment variables:

• REACT_APP_RECAPTHA_SITE_KEY - For Create React App
• NEXT_PUBLIC_RECAPTHA_SITE_KEY - For Next.js

TypeScript Support

This package is written in TypeScript and includes full type definitions. You'll get autocomplete and type checking out of the box.

import { useGoogleReCaptcha, IReCaptchaInstance } from 'use-google-recaptcha';

// All types are exported for your convenience
const { execute, executing } = useGoogleReCaptcha();

Backend Verification

Remember to verify the reCAPTCHA token on your backend:

// Example Node.js/Express verification
app.post('/api/verify-recaptcha', async (req, res) => {
  const { token } = req.body;
  
  const response = await fetch('https://www.google.com/recaptcha/api/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: `secret=${process.env.RECAPTCHA_SECRET_KEY}&response=${token}`
  });
  
  const data = await response.json();
  
  if (data.success && data.score > 0.5) {
    // Token is valid and score is acceptable
    res.json({ success: true });
  } else {
    // Token is invalid or score is too low
    res.status(400).json({ error: 'reCAPTCHA verification failed' });
  }
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Dmitrii Selikhov

Links

• npm package
• GitHub repository
• Google reCAPTCHA v3 Documentation