React SDK

React wrapper for the gkCAPTCHA Web Component

Installation

terminal

npm install @gkcaptcha/react

Quickstart

LoginForm.tsx

import { GkCaptcha } from '@gkcaptcha/react'

export function LoginForm() {
  const handleVerify = async (token: string) => {
    const res = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ captchaToken: token }),
    })
  }

  return (
    <form>
      <GkCaptcha
        siteKey="pk_live_your_site_key"
        onVerify={handleVerify}
      />
      <button type="submit">Login</button>
    </form>
  )
}

Imperative API

InvisibleCaptcha.tsx

import { GkCaptcha, useGkCaptcha } from '@gkcaptcha/react'

export function InvisibleCaptcha() {
  const { ref, execute, reset } = useGkCaptcha()

  return (
    <>
      <GkCaptcha
        ref={ref}
        siteKey="pk_live_your_site_key"
        mode="invisible"
        onVerify={(token) => console.log('token:', token)}
      />
      <button onClick={() => execute()}>Verify Me</button>
      <button onClick={() => reset()}>Reset</button>
    </>
  )
}

Props

Prop	Type	Default	Description / الوصف
siteKey	string	required	Site key from gatekeeper.sa dashboard / مفتاح الموقع من لوحة التحكم
onVerify	(token: string) => void	—	Called when CAPTCHA passes / يُستدعى عند نجاح التحقق
onError	(error: string) => void	—	Called on widget error / عند حدوث خطأ
onExpire	() => void	—	Called when token expires / عند انتهاء صلاحية الرمز
mode	checkbox \| invisible \| overlay	checkbox	Widget display mode / وضع العرض
theme	light \| dark \| auto	auto	Color theme / سمة الألوان
size	normal \| compact	normal	Widget size / حجم الودجت
lang	string	auto	Language code e.g. ar, en / رمز اللغة مثل ar أو en
baseUrl	string	CDN URL	Override widget CDN / تجاوز رابط CDN
disabled	boolean	false	Disable pointer events / تعطيل أحداث المؤشر

Environment Variables

Override the CDN base URL for local development with the baseUrl prop.

DevSetup.tsx

<GkCaptcha
  siteKey="pk_test_..."
  baseUrl="http://localhost:8080/gkcaptcha/v1"
  onVerify={handleVerify}
/>

TypeScript Types

All props are typed via @gkcaptcha/types

types.ts

import type { GkCaptchaProps, GkCaptchaRef } from '@gkcaptcha/types'