Lit
Using better-captcha with Lit
Installation
npm i @better-captcha/litBasic 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:
| Provider | Element 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/Event | Type | Description |
|---|---|---|
onReady / ready | Property / Event | Called/emitted when widget is ready (receives handle) |
onSolve / solve | Property / Event | Called/emitted when challenge is solved (receives token) |
onError / error | Property / Event | Called/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/Property | Type | Required | Description |
|---|---|---|---|
sitekey | string | ✅ | Your provider's site key |
options | object | ❌ | Provider-specific configuration options |
autoRender | boolean | ❌ | Whether to render automatically on mount (default: true) |
scriptOptions | object | ❌ | Script loading configuration (see Script Options) |
onReady | function | ❌ | Callback when widget is ready |
onSolve | function | ❌ | Callback when challenge is solved |
onError | function | ❌ | Callback when an error occurs |
Handle Methods
All providers implement these methods on the handle:
Prop
Type
Available Providers
| Provider | Import Path | Element 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.