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 / تعطيل أحداث المؤشر
logoUrl	string	—	White-label logo. Applies only when the site's plan permits (Enterprise / whiteLabelAllowed); ignored otherwise. / شعار العلامة التجارية. يُطبَّق فقط عندما تسمح خطة الموقع بذلك.
hideFooter	boolean	false	Hide the “Protected by” footer. Applies only when the site's plan permits (Enterprise / whiteLabelAllowed). / إخفاء التذييل. يُطبَّق فقط عندما تسمح خطة الموقع بذلك.

The logoUrl and hideFooter branding props apply only when the site's plan permits white-label (Enterprise). Enforcement is server-side via the same whiteLabelAllowed entitlement — non-Enterprise sites keep the gatekeeper watermark on free challenges, so these props are ignored unless the plan grants them.

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'