SDK React

Componente y hook oficiales de React para el CAPTCHA de CaptchaLa — publicados como @captcha-la/react.

Demo en vivo

📦

demo-v1.captcha.la/react — demo ejecutable con los cuatro modos de producto. Fuente: Captcha-La/react-example.

Instalación

npm install @captcha-la/react
# or
yarn add @captcha-la/react
# or
pnpm add @captcha-la/react

Dependencias entre pares: react@^17 || ^18 || ^19, react-dom@^17 || ^18 || ^19.

Inicio rápido

Componente

import { Captchala } from '@captcha-la/react'

function App() {
  return (
    <Captchala
      appKey="your-app-key"
      product="popup"
      onSuccess={(result) => console.log('pass_token:', result.token)}
      onError={(err) => console.error(err)}
    />
  )
}

Hook

import { useCaptchala } from '@captcha-la/react'

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

  async function handleSubmit(e) {
    e.preventDefault()
    const result = await verify()
    // result.token → submit with the form
  }

  return (
    <form onSubmit={handleSubmit}>
      <button type="submit" disabled={!ready}>Login</button>
    </form>
  )
}

Props

Prop	Tipo	Por defecto	Descripción
appKey	string	obligatorio	Clave de aplicación de CaptchaLa
serverToken	string	-	Token de desafío de un solo uso emitido por el servidor. Obligatorio cuando la aplicación tiene server_token_required=true.
product	'popup' | 'float' | 'embed' | 'bind'	'popup'	Modo de visualización
action	string	'default'	Identificador de acción
lang	string	'zh-CN'	Código de idioma
onSuccess	(result) => void	-	Callback de éxito
onError	(error) => void	-	Callback de error
onClose	() => void	-	Callback de cierre
onReady	() => void	-	Callback de listo
className	string	-	Nombre de clase del contenedor
style	CSSProperties	-	Estilos en línea del contenedor

Métodos (vía ref)

import { useRef } from 'react'
import { Captchala, type CaptchalaRef } from '@captcha-la/react'

function App() {
  const ref = useRef<CaptchalaRef>(null)
  return (
    <>
      <Captchala ref={ref} appKey="your-app-key" />
      <button onClick={() => ref.current?.verify()}>Verify</button>
    </>
  )
}

Método	Descripción
verify()	Lanza la verificación
reset()	Reinicia el estado del CAPTCHA
destroy()	Destruye la instancia
bindTo(selector)	Enlaza al elemento (para el modo bind)
setLang(lang)	Cambia el idioma en caliente

Producción: modo serverToken

import { useState, useEffect } from 'react'
import { Captchala } from '@captcha-la/react'

function LoginPage() {
  const [token, setToken] = useState<string>()

  useEffect(() => {
    fetch('/api/captcha-token')         // your own backend
      .then((r) => r.json())
      .then((d) => setToken(d.server_token))
  }, [])

  if (!token) return <div>Loading…</div>

  return (
    <Captchala
      serverToken={token}
      appKey="pk_your_public_app_key"
      action="login"
      onSuccess={(r) => console.log('pass_token:', r.token)}
    />
  )
}

Consulta la Referencia de la API para el contrato completo del backend.

Enlaces

• npm · GitHub · ejemplo
• Visión general del SDK Web · Referencia de la API