React SDK

Component + hook React chính thức cho CaptchaLa CAPTCHA — phát hành dưới dạng @captcha-la/react.

Demo trực tiếp

📦

demo-v1.captcha.la/react — demo chạy được với cả bốn chế độ sản phẩm. Mã nguồn: Captcha-La/react-example.

Cài đặt

npm install @captcha-la/react
# hoặc
yarn add @captcha-la/react
# hoặc
pnpm add @captcha-la/react

Peer dependencies: react@^17 || ^18 || ^19, react-dom@^17 || ^18 || ^19.

Bắt đầu nhanh

Component

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 → gửi kèm form
  }

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

Props

Prop	Kiểu	Mặc định	Mô tả
appKey	string	bắt buộc	Khóa ứng dụng CaptchaLa
serverToken	string	-	Token thử thách do máy chủ phát hành, dùng một lần. Bắt buộc khi ứng dụng có server_token_required=true.
product	'popup' | 'float' | 'embed' | 'bind'	'popup'	Chế độ hiển thị
action	string	'default'	Định danh hành động
lang	string	'zh-CN'	Mã ngôn ngữ
onSuccess	(result) => void	-	Callback khi thành công
onError	(error) => void	-	Callback khi lỗi
onClose	() => void	-	Callback khi đóng
onReady	() => void	-	Callback khi sẵn sàng
className	string	-	Tên class của container
style	CSSProperties	-	Inline style của container

Phương thức (qua 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>
    </>
  )
}

Phương thức	Mô tả
verify()	Kích hoạt xác minh
reset()	Đặt lại trạng thái CAPTCHA
destroy()	Hủy instance
bindTo(selector)	Gắn vào phần tử (cho chế độ bind)
setLang(lang)	Đổi ngôn ngữ tại chỗ

Production: chế độ serverToken

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

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

  useEffect(() => {
    fetch('/api/captcha-token')         // backend của bạn
      .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)}
    />
  )
}

Xem Tài liệu API để biết toàn bộ hợp đồng phía backend.

Liên kết

• npm · GitHub · ví dụ
• Tổng quan Web SDK · Tài liệu API