react-gocaptcha

A modern, ultra-flexible, multi-mode React CAPTCHA component for self-hosted Go CAPTCHA servers.

react-gocaptcha connects seamlessly to any backend running the go-captcha server. The server dictates the CAPTCHA challenge type, while react-gocaptcha handles rich visual rendering, dynamic interaction, responsive scaling, and event callbacks.

Features

• 4 CAPTCHA Modes Supported Out of the Box:
  • 🔤 Text CAPTCHA: Distorted text challenge with noise reduction and text entry.
  • 🖼️ Image Selection CAPTCHA: Tile grid matching with text-mode question prompts.
  • 🧩 Photorealistic Nature Wallpaper Puzzle: Scenic missing-piece puzzle with candidate choice matching.
  • 🎚️ Drag-to-Align Slider: Real-time percentage-responsive tile slider overlay.
• ⚡ Scale-Invariant & Responsive: Smooth percentage-based calculations adapt to mobile, tablet, and desktop views seamlessly.
• 🎨 Fully Customizable: Easily override CSS tokens or pass custom classes to match your design system.
• 📘 TypeScript Ready: Complete .d.ts definitions out of the box.

Installation

npm install react-gocaptcha
# or
yarn add react-gocaptcha
# or
pnpm add react-gocaptcha

Quick Start

import React from 'react'
import { Captcha } from 'react-gocaptcha'
import 'react-gocaptcha/style.css'

export default function App() {
  const handleSuccess = (result) => {
    console.log('CAPTCHA verified successfully!', result)
  }

  const handleError = (error) => {
    console.error('CAPTCHA error:', error)
  }

  return (
    <div style={{ maxWidth: '420px', margin: '40px auto' }}>
      <h2>Secure Form Verification</h2>
      <Captcha
        endpoint="/captcha"
        onSuccess={handleSuccess}
        onError={handleError}
      />
    </div>
  )
}

Props API

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | endpoint | string | "/captcha" | URL of the backend Go CAPTCHA handler (e.g. /captcha, /captcha/text, /captcha/puzzle, /captcha/slider). | | onSuccess | (result: { status: string }) => void | undefined | Callback fired when the user completes verification successfully. | | onError | (error: Error) => void | undefined | Callback fired on network or verification error. | | onChallengeLoad | (metadata: CaptchaMetadata) => void | undefined | Callback fired when a new challenge metadata is loaded. | | className | string | "" | Optional CSS class name for the wrapper element. |

Publishing to npmjs

To publish this library to npmjs.com:

# 1. Login to your npm account
npm login

# 2. Build the package
npm run build

# 3. Publish to npmjs
npm publish --access public

Author & Document Signature

Lead Engineer: Om Prakash Tiwari
License: MIT