Better Captcha

Lit

Using better-captcha with Lit

Installation

npm i @better-captcha/lit

Basic Usage

import { ReCaptcha } from "@better-captcha/lit/provider/recaptcha";

// The component is automatically registered as a custom element
<recaptcha-captcha sitekey="your-site-key"></recaptcha-captcha>

Custom Element Names

Each provider is registered as a custom element with its own tag name:

ProviderElement Name
Turnstile<turnstile-captcha>
hCaptcha<hcaptcha-captcha>
reCAPTCHA<recaptcha-captcha>
Friendly Captcha<friendly-captcha>
Private Captcha<private-captcha-widget>
Captcha Fox<captcha-fox-captcha>
Prosopo<prosopo-captcha>
CapWidget<cap-widget-captcha>

Imperative Handle

Lit web components expose a getHandle() method to access the imperative handle for programmatic control.

import { ReCaptcha } from "@better-captcha/lit/provider/recaptcha";

const captcha = document.querySelector('recaptcha-captcha');
const handle = captcha.getHandle();

// Execute the captcha
handle.execute();

// Reset the captcha
handle.reset();

// Get the response token
const response = handle.getResponse();
console.log(response);

Lifecycle Callbacks

All captcha components support three lifecycle callbacks via both properties and custom events.

Using Properties

import { ReCaptcha } from "@better-captcha/lit/provider/recaptcha";

const captcha = document.querySelector('recaptcha-captcha') as ReCaptcha;

captcha.onReady = (handle) => {
  console.log("Captcha is ready", handle);
};

captcha.onSolve = (token: string) => {
  console.log("Captcha solved with token:", token);
  // Send token to your backend for verification
};

captcha.onError = (error: Error | string) => {
  console.error("Captcha error:", error);
};

Using Custom Events

const captcha = document.querySelector('recaptcha-captcha');

captcha.addEventListener('ready', (e) => {
  console.log("Captcha ready", e.detail);
});

captcha.addEventListener('solve', (e) => {
  console.log("Captcha solved", e.detail.token);
});

captcha.addEventListener('error', (e) => {
  console.error("Captcha error", e.detail.error);
});
Callback/EventTypeDescription
onReady / readyProperty / EventCalled/emitted when widget is ready (receives handle)
onSolve / solveProperty / EventCalled/emitted when challenge is solved (receives token)
onError / errorProperty / EventCalled/emitted when an error occurs (receives error)

Setting Options

Configure the widget via attributes for simple values or properties for complex objects.

<!-- Via attributes (for simple values) -->
<recaptcha-captcha sitekey="your-site-key"></recaptcha-captcha>
// Via properties (for complex objects)
const captcha = document.querySelector('recaptcha-captcha');
captcha.options = { theme: 'dark', size: 'compact' };
captcha.scriptOptions = { autoLoad: false, timeout: 30000 };

Manual Rendering

By default, captchas automatically render on mount. For more control, disable auto-rendering and trigger it manually.

<recaptcha-captcha sitekey="your-site-key" autoRender="false"></recaptcha-captcha>
<button onclick="showCaptcha()">Show Captcha</button>
const captcha = document.querySelector('recaptcha-captcha');
const handle = captcha.getHandle();

function showCaptcha() {
  handle.render();
}

Common Attributes & Properties

Attribute/PropertyTypeRequiredDescription
sitekeystring✅Your provider's site key
optionsobject❌Provider-specific configuration options
autoRenderboolean❌Whether to render automatically on mount (default: true)
scriptOptionsobject❌Script loading configuration (see Script Options)
onReadyfunction❌Callback when widget is ready
onSolvefunction❌Callback when challenge is solved
onErrorfunction❌Callback when an error occurs

Handle Methods

All providers implement these methods on the handle:

Prop

Type

Available Providers

ProviderImport PathElement Name
ReCaptcha@better-captcha/lit/provider/recaptcha<recaptcha-captcha>
HCaptcha@better-captcha/lit/provider/hcaptcha<hcaptcha-captcha>
Turnstile@better-captcha/lit/provider/turnstile<turnstile-captcha>
Friendly Captcha@better-captcha/lit/provider/friendly-captcha<friendly-captcha>
Private Captcha@better-captcha/lit/provider/private-captcha<private-captcha-widget>
Captcha Fox@better-captcha/lit/provider/captcha-fox<captcha-fox-captcha>
Prosopo@better-captcha/lit/provider/prosopo<prosopo-captcha>
CapWidget@better-captcha/lit/provider/cap-widget<cap-widget-captcha>

See the Provider Documentation for provider-specific options and configuration.

On this page