svelte-recaptcha-v2

Google reCAPTCHA v2 implementation for Svelte SPA, SSR and sveltekit static sites.

Features

• [x] svelte server side rendering (SSR) friendly.
• [x] works with sveltekit SPA, SSR and static site adapters.
• [x] easy integration with third party form validation libraries.
• [x] fail-safe loader to inject recaptcha.
• [x] invisible recaptcha or checkbox recaptcha support.
• [x] event model for intercepting various recaptcha states.
• [x] handle all your form logic in a single submit handler.
• [x] proper DOM cleanup (deletes recaptcha completely)
• [x] documented, debug.js friendly source code.
• [x] typescript definitions are included for LSP.

Demonstration

svelte-recaptcha-v2 demo

Getting Started

# install as a development dependency
pnpm install -D svelte-recaptcha-v2

Basic Usage

Import the library onto your template and update your google key:

import { Recaptcha, recaptcha, observer } from "svelte-recaptcha-v2";
/*
 │Recaptcha: svelte <Recaptcha> component.
 │recaptcha: google method, gives you recaptcha.execute().
 │observer: allows you to track captcha state across components.
 */

const googleRecaptchaSiteKey="replace_with_yours";

In your form, add the component:

<Recaptcha
    sitekey={googleRecaptchaSiteKey}
    badge={"top"}
    size={"invisible"}
    theme={"light"}
    on:success={onCaptchaSuccess}
    on:error={onCaptchaError}
    on:expired={onCaptchaExpire}
    on:close={onCaptchaClose}
    on:ready={onCaptchaReady} />

Setup your event handlers:

const onCaptchaReady = (event) => {
    console.log("recaptcha init has completed.")
    /*
     │You can enable your form button here.
     */
};

const onCaptchaSuccess = (event) => {
    userTracker.resolve(event);
    console.log("token received: " + event.detail.token);
    /*
     │If using checkbox method, you can attach your
     │form logic here, or dispatch your custom event.
     */
};

const onCaptchaError = (event) => {
    console.log("recaptcha init has failed.");
    /*
     │Usually due to incorrect siteKey.
     |Make sure you have the correct siteKey..
     */
};

const onCaptchaExpire = (event) => {
    console.log("recaptcha api has expired");
    /*
     │Normally, you wouldn't need to do anything.
     │Recaptcha should reinit itself automatically.
     */
};

const onCaptchaOpen = (event) => {
    console.log("google decided to challange the user");
    /*
     │This fires when the puzzle frame pops.
     */
};

const onCaptchaClose = (event) => {
    console.log("google decided to challange the user");
    /*
     │This fires when the puzzle frame closes.
     │Usually happens when the user clicks outside
     |the modal frame.
     */
};

Update your form handler:

const submitHandler = async () => {
    console.log("launching recaptcha");
    recaptcha.execute();

    console.log("pending for google response");
    const event = await Promise.resolve(observer);

    const recaptchaToken = event.detail?.token ? event.detail.token : false;

    if (!recaptchaToken) {
        console.log("recaptcha is NOT OK");
        return false;
    }

    console.log("token retrieved", recaptchaToken);
};

Debugging

If you would like to enable client side debugging, add {Recaptcha} value to your localStorage DEBUG key.

Issues

If any trouble, please create an issue. PRs are most welcome.

Todo

• [] add recipes for validation libraries (felte, stock etc)
• [] look into mutation observers