SolidJS

Installation

npm i @better-captcha/solidjs

Basic Usage

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

export default function Example() {
  return <ReCaptcha sitekey="your-site-key" />;
}

Imperative Handle

SolidJS uses a controller pattern with createCaptchaController to access the imperative handle in a reactive way.

import { ReCaptcha, type ReCaptchaHandle, createCaptchaController } from "@better-captcha/solidjs/provider/recaptcha";

export default function Example() {
  const controller = createCaptchaController<ReCaptchaHandle>();

  return (
    <>
      <ReCaptcha sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" controller={controller} />
      <button onClick={() => controller.handle()?.execute()}>Execute</button>
      <button onClick={() => controller.handle()?.reset()}>Reset</button>
      <button onClick={() => console.log(controller.handle()?.getResponse())}>Log response</button>
    </>
  );
}

The controller's handle() function returns the handle once the widget is ready, or null if not yet initialized. Always use optional chaining (?.) when calling methods.

Lifecycle Callbacks

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

import { ReCaptcha, type ReCaptchaHandle, createCaptchaController } from "@better-captcha/solidjs/provider/recaptcha";

export default function Example() {
  const controller = createCaptchaController<ReCaptchaHandle>();

  const handleReady = (handle: ReCaptchaHandle) => {
    console.log("Captcha is ready", handle);
  };

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

  const handleError = (error: Error) => {
    console.error("Captcha error:", error);
  };

  return (
    <ReCaptcha
      sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
      controller={controller}
      onReady={handleReady}
      onSolve={handleSolve}
      onError={handleError}
    />
  );
}

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.

import { ReCaptcha, createCaptchaController } from "@better-captcha/solidjs/provider/recaptcha";

export default function Example() {
  const controller = createCaptchaController();

  return (
    <>
      <ReCaptcha 
        sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI" 
        controller={controller} 
        autoRender={false} 
      />
      <button onClick={async () => await controller.handle()?.render()}>Show Captcha</button>
    </>
  );
}

Common Props

Prop	Type	Required	Description
`sitekey`	`string`	✅	Your provider's site key
`controller`	`Controller`	❌	Controller from `createCaptchaController()` for imperative access
`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/solidjs/provider/recaptcha`
HCaptcha	`@better-captcha/solidjs/provider/hcaptcha`
Turnstile	`@better-captcha/solidjs/provider/turnstile`
Friendly Captcha	`@better-captcha/solidjs/provider/friendly-captcha`
Private Captcha	`@better-captcha/solidjs/provider/private-captcha`
Captcha Fox	`@better-captcha/solidjs/provider/captcha-fox`
Prosopo	`@better-captcha/solidjs/provider/prosopo`
CapWidget	`@better-captcha/solidjs/provider/cap-widget`

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

SolidJS

On this page