LogoBetter 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
sitekeystringYour provider's site key
optionsobjectProvider-specific configuration options
autoRenderbooleanWhether to render automatically on mount (default: true)
scriptOptionsobjectScript loading configuration (see Script Options)
onReadyfunctionCallback when widget is ready
onSolvefunctionCallback when challenge is solved
onErrorfunctionCallback 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