svelte-captcha-enhance

A lightweight SvelteKit utility that adds CAPTCHA protection to your forms with progressive enhancement. Supports reCAPTCHA v3, hCaptcha, and Cloudflare Turnstile.

Features

• 🔒 Multiple CAPTCHA providers: reCAPTCHA v3, hCaptcha, and Cloudflare Turnstile
• 📦 Easy integration: Extends SvelteKit's enhance function with CAPTCHA support
• 🎯 TypeScript support: Fully typed for better developer experience
• 🪶 Lightweight: Minimal bundle size impact

Installation

npm install svelte-captcha-enhance

Quick Start

reCAPTCHA v3

<script>
  import { env } from '$env/dynamic/public';
  import enhance from 'svelte-captcha-enhance';
</script>

<svelte:head>
  <script src="https://www.google.com/recaptcha/api.js?render={env.PUBLIC_RECAPTCHA_SITEKEY}"></script>
</svelte:head>

<form
  method="post"
  use:enhance={{
    type: 'recaptcha',
    sitekey: env.PUBLIC_RECAPTCHA_SITEKEY,
    action: 'submit',
    submit: ({ formData }) => ({ result }) => {
      console.log('Form submitted:', result);
    }
  }}
>
  <input type="text" name="name" placeholder="Your name" required />
  <button type="submit">Submit</button>
</form>

hCaptcha

<script>
  import { env } from '$env/dynamic/public';
  import enhance from 'svelte-captcha-enhance';
</script>

<svelte:head>
  <script src="https://js.hcaptcha.com/1/api.js" async defer></script>
</svelte:head>

<div class="h-captcha" data-sitekey={env.PUBLIC_HCAPTCHA_SITEKEY}></div>

<form
  method="post"
  use:enhance={{
    type: 'hcaptcha',
    submit: ({ formData }) => ({ result }) => {
      console.log('Form submitted:', result);
    }
  }}
>
  <input type="text" name="name" placeholder="Your name" required />
  <button type="submit">Submit</button>
</form>

Cloudflare Turnstile

<script>
  import { env } from '$env/dynamic/public';
  import enhance from 'svelte-captcha-enhance';
</script>

<svelte:head>
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</svelte:head>

<form
  method="post"
  use:enhance={{
    type: 'turnstile',
    sitekey: env.PUBLIC_TURNSTILE_SITEKEY,
    submit: ({ formData }) => ({ result }) => {
      console.log('Form submitted:', result);
    }
  }}
>
  <input type="text" name="name" placeholder="Your name" required />
  <button type="submit">Submit</button>
</form>

API Reference

Configuration Options

Common Options

Option	Type	Description
submit	SubmitFunction	Optional callback function (same as SvelteKit's enhance)

reCAPTCHA Options

Option	Type	Required	Description
type	'recaptcha'	✅	CAPTCHA provider type
sitekey	string	✅	Your reCAPTCHA site key
action	string	❌	Action name for reCAPTCHA v3 (default: 'submit')

hCaptcha Options

Option	Type	Required	Description
type	'hcaptcha'	✅	CAPTCHA provider type
widget	string	❌	Widget ID (uses first widget if unspecified)

Turnstile Options

Option	Type	Required	Description
type	'turnstile'	✅	CAPTCHA provider type
sitekey	string	✅	Your Turnstile site key
container	string | HTMLElement	❌	Container element (uses form if unspecified)
theme	'light' | 'dark' | 'auto'	❌	Theme (default: 'auto')
size	'normal' | 'invisible' | 'compact'	❌	Size (default: 'normal')
language	string | 'auto'	❌	Language (default: 'auto')

Bypass Mode

For development or testing purposes:

<form
  method="post"
  use:enhance={{
    type: 'bypass',
    submit: ({ formData }) => ({ result }) => {
      console.log('Form submitted without CAPTCHA');
    }
  }}
>
  <!-- form content -->
</form>

Server-Side Validation

This library handles the client-side CAPTCHA integration only. You'll need to implement server-side validation yourself using your CAPTCHA provider's verification API. The CAPTCHA responses will be available in your form data as:

• g-recaptcha-response (reCAPTCHA)
• h-captcha-response (hCaptcha)
• cf-turnstile-response (Turnstile)

Examples

Check out the examples directory for complete working examples of each CAPTCHA provider.