@gkcaptcha/react

React wrapper for the gkCAPTCHA Web Component.

Requirements

• React >= 18
• Node.js >= 18

Installation

npm install @gkcaptcha/react

Quickstart

import { GkCaptcha } from '@gkcaptcha/react'

export function LoginForm() {
  const handleVerify = async (token: string) => {
    // Send token to your server for verification
    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

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>
    </>
  )
}

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') | | baseUrl | string | CDN URL | Override widget CDN base URL | | disabled | boolean | false | Disable pointer events |

Environment Variables

The component uses the CDN at https://gkcaptcha.gatekeeper.sa/widget by default. Override with the baseUrl prop for development:

<GkCaptcha
  siteKey="pk_test_..."
  baseUrl="https://gkcaptcha.gatekeeper.sa/widget"
  onVerify={handleVerify}
/>