Svelte

Installation

npm i @better-captcha/svelte

Basic Usage

<script lang="ts">
import ReCaptcha from "@better-captcha/svelte/provider/recaptcha";
</script>

<ReCaptcha sitekey="your-site-key" />

Imperative Handle

Svelte uses bind:this to access component methods directly through a component reference.

<script lang="ts">
import ReCaptcha from "@better-captcha/svelte/provider/recaptcha";
import type { ReCaptchaHandle } from "@better-captcha/svelte/provider/recaptcha";

let captchaRef: ReCaptcha | undefined;

function onReady(handle: ReCaptchaHandle) {
  console.log("Captcha ready", handle);
}

function execute() {
  captchaRef?.execute();
}

function reset() {
  captchaRef?.reset();
}

function logResponse() {
  console.log(captchaRef?.getResponse());
}
</script>

<ReCaptcha
  bind:this={captchaRef}
  sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
  onready={onReady}
/>
<button onclick={execute}>Execute</button>
<button onclick={reset}>Reset</button>
<button onclick={logResponse}>Log response</button>

Use bind:this to get a reference to the component instance, then call methods directly on it. Always use optional chaining (?.) since the reference may be undefined initially.

Lifecycle Callbacks

All captcha components support three lifecycle callbacks for handling different stages of the widget lifecycle.

<script lang="ts">
import ReCaptcha from "@better-captcha/svelte/provider/recaptcha";
import type { ReCaptchaHandle } from "@better-captcha/svelte/provider/recaptcha";

function onReady(handle: ReCaptchaHandle) {
  console.log("Captcha is ready", handle);
}

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

function onError(error: Error) {
  console.error("Captcha error:", error);
}
</script>

<ReCaptcha
  sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
  onready={onReady}
  onSolve={onSolve}
  onerror={onError}
/>

Callback	Parameters	Description
`onready`	`(handle: Handle) => void`	Called when the widget is rendered and ready (receives handle)
`onSolve`	`(token: string) => void`	Called when the challenge is solved with the response token
`onerror`	`(error: Error) => void`	Called when an error occurs during initialization or solving

Manual Rendering

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

<script lang="ts">
import ReCaptcha from "@better-captcha/svelte/provider/recaptcha";

let captchaRef: ReCaptcha | undefined;

function render() {
  captchaRef?.render();
}
</script>

<ReCaptcha 
  bind:this={captchaRef} 
  sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" 
  autoRender={false} 
/>
<button onclick={render}>Show Captcha</button>

Common Props

Prop	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
ReCaptcha	`@better-captcha/svelte/provider/recaptcha`
HCaptcha	`@better-captcha/svelte/provider/hcaptcha`
Turnstile	`@better-captcha/svelte/provider/turnstile`
Friendly Captcha	`@better-captcha/svelte/provider/friendly-captcha`
Private Captcha	`@better-captcha/svelte/provider/private-captcha`
Captcha Fox	`@better-captcha/svelte/provider/captcha-fox`
Prosopo	`@better-captcha/svelte/provider/prosopo`
CapWidget	`@better-captcha/svelte/provider/cap-widget`

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

Svelte

On this page