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

``bash
npm install svelte-captcha-enhance
`

Quick Start

$3

`svelte


method="post"
use:enhance={{
type: 'recaptcha',
sitekey: env.PUBLIC_RECAPTCHA_SITEKEY,
action: 'submit',
submit: ({ formData }) => ({ result }) => {
console.log('Form submitted:', result);
}
}}
>

Submit

`

$3

`svelte


method="post"
use:enhance={{
type: 'hcaptcha',
submit: ({ formData }) => ({ result }) => {
console.log('Form submitted:', result);
}
}}
>

Submit

`

$3

`svelte


method="post"
use:enhance={{
type: 'turnstile',
sitekey: env.PUBLIC_TURNSTILE_SITEKEY,
submit: ({ formData }) => ({ result }) => {
console.log('Form submitted:', result);
}
}}
>

Submit

`

API Reference

$3

#### 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:

`svelte
method="post"
use:enhance={{
type: 'bypass',
submit: ({ formData }) => ({ result }) => {
console.log('Form submitted without CAPTCHA');
}
}}
>


`

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.