@captchala/react

Official Captchala CAPTCHA React component - Smart CAPTCHA protection for your React applications.

Installation

npm install @captchala/react
# or
yarn add @captchala/react
# or
pnpm add @captchala/react

Quick Start

Component Approach

import { Captchala } from '@captchala/react'

function App() {
  const handleSuccess = (result) => {
    console.log('Verification successful!')
    console.log('Token:', result.token)
    // Send token to your server for validation
  }

  return (
    <Captchala
      appKey="your-app-key"
      product="popup"
      onSuccess={handleSuccess}
      onError={(err) => console.error(err)}
    />
  )
}

Hook Approach

import { useCaptchala } from '@captchala/react'

function LoginForm() {
  const { ready, verify } = useCaptchala({
    appKey: 'your-app-key',
    product: 'bind',
    action: 'login'
  })

  const handleSubmit = async (e) => {
    e.preventDefault()

    try {
      const result = await verify()
      console.log('Token:', result.token)
      // Continue with form submission
    } catch (err) {
      console.error('Verification failed:', err)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />
      <button type="submit" disabled={!ready}>
        Login
      </button>
    </form>
  )
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | appKey | string | required | Your Captchala application key | | product | 'popup' \| 'float' \| 'embed' \| 'bind' | 'popup' | Display mode | | action | string | 'default' | Action identifier (e.g., 'login', 'register', 'checkout') | | lang | string | 'zh-CN' | Language code ('zh-CN', 'en', 'ja', etc.) | | onSuccess | (result) => void | - | Success callback | | onError | (error) => void | - | Error callback | | onClose | () => void | - | Close callback | | onReady | () => void | - | Ready callback | | className | string | - | Container class name | | style | CSSProperties | - | Container inline styles |

Methods (via ref)

import { useRef } from 'react'
import { Captchala, CaptchalaRef } from '@captchala/react'

function App() {
  const captchaRef = useRef<CaptchalaRef>(null)

  const handleManualVerify = () => {
    captchaRef.current?.verify()
  }

  return (
    <>
      <Captchala ref={captchaRef} appKey="your-key" />
      <button onClick={handleManualVerify}>Verify</button>
    </>
  )
}

| Method | Description | |--------|-------------| | verify() | Trigger verification | | reset() | Reset CAPTCHA state | | destroy() | Destroy CAPTCHA instance | | bindTo(selector) | Bind to element (for 'bind' mode) |

useCaptchala Hook

const {
  ready,      // boolean - SDK is loaded and ready
  loading,    // boolean - SDK is loading
  error,      // Error | null - Loading error
  verify,     // () => Promise<CaptchalaResult> - Trigger verification
  reset,      // () => void - Reset state
  bindTo,     // (selector) => void - Bind to element
  appendTo    // (selector) => void - Append to element
} = useCaptchala(options)

Display Modes

Popup Mode (Default)

Shows a button that triggers a popup CAPTCHA dialog.

<Captchala appKey="your-key" product="popup" />

Float Mode

Displays an inline floating CAPTCHA widget.

<Captchala appKey="your-key" product="float" />

Embed Mode

Embeds the CAPTCHA directly in the page.

<Captchala appKey="your-key" product="embed" />

Bind Mode with Hook

Best for form submissions - verifies when the user submits.

function Form() {
  const { ready, verify } = useCaptchala({
    appKey: 'your-key',
    product: 'bind'
  })

  const handleSubmit = async () => {
    const result = await verify()
    // result.token contains the verification token
  }

  return <button onClick={handleSubmit} disabled={!ready}>Submit</button>
}

Server-side Validation

After receiving the token from onSuccess, validate it on your server:

// Your backend
const response = await fetch('https://api.captcha.la/v1/risk/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Key': 'your-app-key',
    'X-App-Secret': 'your-app-secret'
  },
  body: JSON.stringify({ token })
})

const result = await response.json()
if (result.code === 0 && result.data.valid) {
  // Token is valid, proceed with the request
}

TypeScript Support

Full TypeScript support is included:

import {
  Captchala,
  useCaptchala,
  type CaptchalaProps,
  type CaptchalaResult,
  type CaptchalaRef,
  type UseCaptchalaOptions
} from '@captchala/react'

License

MIT License - see LICENSE for details.

Links

• Documentation
• Dashboard
• GitHub