turnstile-svelte 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# turnstile-svelte
+
+A highly flexible and reactive [Cloudflare Turnstile](https://developers.cloudflare.com/turnstile/) component and action tailored specifically for **Svelte 5**.
+
+This library allows you to seamlessly integrate Cloudflare's privacy-preserving CAPTCHA alternative into your Svelte applications. It provides two methods of usage depending on your needs: a drop-in Component (`<TurnstileWidget>`) or a Svelte Action (`use:turnstileAction`) for advanced custom integrations.
+
+## Installation
+
+Install the library using your preferred package manager:
+
+```bash
+npm install turnstile-svelte
+# or
+pnpm add turnstile-svelte
+# or
+yarn add turnstile-svelte
+```
+
+## Features
+- 🚀 **Svelte 5 Ready**: Built with Svelte 5 Runes in mind.
+- 🔌 **Plug and Play**: The widget component takes care of injecting the Cloudflare Turnstile script into the document dynamically if it isn't already present.
+- 🔄 **Reactive Options**: Options like `theme`, `size`, or your custom callbacks are fully reactive. Changing them will automatically re-render the widget gracefully without memory leaks.
+- 🛡️ **Fully Typed**: Includes comprehensive TypeScript definitions matching the official Cloudflare Turnstile API.
+
+## Usage
+
+### 1. Using the Component (Recommended)
+
+The easiest way to use the library is by importing the `TurnstileWidget` component.
+
+```svelte
+<script lang="ts">
+  import { TurnstileWidget } from 'turnstile-svelte';
+
+  // Your Cloudflare Turnstile Sitekey
+  const SITE_KEY = '1x00000000000000000000AA';
+  
+  let token = $state<string | null>(null);
+
+  function handleToken(t: string) {
+    console.log('Successfully verified. Token:', t);
+    token = t;
+  }
+
+  function handleError(errorCode: string) {
+    console.error('Turnstile verification failed:', errorCode);
+  }
+</script>
+
+<TurnstileWidget 
+  sitekey={SITE_KEY} 
+  theme="auto" 
+  ontoken={handleToken} 
+  onerror={handleError} 
+/>
+
+{#if token}
+  <p>Success! Form can now be submitted.</p>
+{/if}
+```
+
+### 2. Using the Svelte Action (Advanced)
+
+If you need full control over the wrapper DOM element, you can use the Svelte Action directly on any HTML element.
+
+```svelte
+<script lang="ts">
+  import { turnstileAction } from 'turnstile-svelte';
+  import type { TurnstileOptions } from 'turnstile-svelte';
+
+  const options: TurnstileOptions = {
+    sitekey: '1x00000000000000000000AA',
+    theme: 'dark',
+    callback: (token) => {
+      console.log("Token obtained:", token);
+    }
+  };
+</script>
+
+<!-- The widget will be injected into this div -->
+<div use:turnstileAction={options} class="my-custom-wrapper"></div>
+```
+
+## Props / API Reference
+
+The `TurnstileWidget` component accepts all standard Cloudflare Turnstile parameters as props, with the hyphenated callback names converted to standard Svelte-style event handlers.
+
+| Prop | Type | Description |
+|---|---|---|
+| `sitekey` | `string` | **Required.** Your Cloudflare Turnstile sitekey. |
+| `theme` | `"auto" \| "light" \| "dark"` | The widget theme. (Default: `"auto"`) |
+| `size` | `"normal" \| "flexible" \| "compact"` | The widget size. |
+| `action` | `string` | Customer value used to differentiate widgets under the same sitekey. |
+| `cData` | `string` | Customer payload that can be attached to the challenge. |
+| `language` | `string` | ISO 639-1 language code (e.g. `"en-US"`). (Default: `"auto"`) |
+| `retry` | `"auto" \| "never"` | Controls auto-retry behavior. |
+| `retryInterval` | `number` | Time between retry attempts in ms. (Default: `8000`) |
+| `execution` | `"render" \| "execute"` | When to obtain the token. |
+| `appearance` | `"always" \| "execute" \| "interaction-only"` | When the widget should be visible. |
+
+### Callbacks (Events)
+
+| Prop | Turnstile Equivalent | Description |
+|---|---|---|
+| `ontoken` | `callback` | Invoked upon successful completion. Receives the `token`. |
+| `onerror` | `error-callback` | Invoked on error (e.g. network error). Receives the `errorCode`. |
+| `onexpire` | `expired-callback` | Invoked when the token expires. |
+| `ontimeout` | `timeout-callback` | Invoked when an interactive challenge times out. |
+| `onbeforeinteractive`| `before-interactive-callback`| Invoked before an interactive challenge is shown. |
+| `onafterinteractive` | `after-interactive-callback` | Invoked after an interactive challenge has been completed or failed. |
+| `onunsupported` | `unsupported-callback` | Invoked when the client browser is not supported. |
+
+For a detailed explanation of all options, refer to the [Cloudflare Turnstile Documentation](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/).
+
+## License
+MIT

package/dist/actions/action.d.ts

@@ -0,0 +1,22 @@
+import type { TurnstileOptions } from "../types/types.js";
+/**
+ * Svelte Action to initialize and manage a Cloudflare Turnstile widget on a DOM node.
+ *
+ * @param node - The HTML element where the Turnstile widget will be injected.
+ * @param options - Configuration options for the Turnstile widget.
+ * @returns An object with `update` and `destroy` methods for the Svelte action lifecycle.
+ */
+export declare function turnstileAction(node: HTMLElement, options: TurnstileOptions): {
+    /**
+     * Called by Svelte whenever the options passed to the action change.
+     * Removes the existing widget and re-initializes it with the new options.
+     *
+     * @param newOptions - The updated Turnstile configuration options.
+     */
+    update(newOptions: TurnstileOptions): void;
+    /**
+     * Called by Svelte when the DOM node is removed.
+     * Cleans up the polling interval and removes the Turnstile widget to prevent memory leaks.
+     */
+    destroy(): void;
+};

package/dist/actions/action.js

@@ -0,0 +1,70 @@
+const TURNSTILE_SCRIPT_ID = "cf-turnstile-script";
+const TURNSTILE_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+/**
+ * Svelte Action to initialize and manage a Cloudflare Turnstile widget on a DOM node.
+ *
+ * @param node - The HTML element where the Turnstile widget will be injected.
+ * @param options - Configuration options for the Turnstile widget.
+ * @returns An object with `update` and `destroy` methods for the Svelte action lifecycle.
+ */
+export function turnstileAction(node, options) {
+    let widgetId = null;
+    let renderInterval;
+    /**
+     * Attempts to render the Turnstile widget.
+     * If the global `window.turnstile` object is available, it clears the polling interval
+     * and initializes the widget with the provided options.
+     */
+    function renderWidget() {
+        if (window.turnstile) {
+            clearInterval(renderInterval);
+            widgetId = window.turnstile.render(node, options);
+        }
+    }
+    /**
+     * Injects the Cloudflare Turnstile script into the document if it hasn't been loaded yet.
+     * Starts a polling interval to wait for the `window.turnstile` object to be ready.
+     */
+    function loadScript() {
+        if (document.getElementById(TURNSTILE_SCRIPT_ID) || window.turnstile) {
+            // Script is already injected or loaded. Wait for window.turnstile to be fully ready
+            renderInterval = setInterval(renderWidget, 50);
+            return;
+        }
+        const script = document.createElement("script");
+        script.id = TURNSTILE_SCRIPT_ID;
+        script.src = TURNSTILE_SRC;
+        script.async = true;
+        script.defer = true;
+        document.head.appendChild(script);
+        renderInterval = setInterval(renderWidget, 50);
+    }
+    loadScript();
+    return {
+        /**
+         * Called by Svelte whenever the options passed to the action change.
+         * Removes the existing widget and re-initializes it with the new options.
+         *
+         * @param newOptions - The updated Turnstile configuration options.
+         */
+        update(newOptions) {
+            clearInterval(renderInterval);
+            if (widgetId !== null && window.turnstile) {
+                window.turnstile.remove(widgetId);
+                widgetId = null;
+            }
+            options = newOptions;
+            loadScript();
+        },
+        /**
+         * Called by Svelte when the DOM node is removed.
+         * Cleans up the polling interval and removes the Turnstile widget to prevent memory leaks.
+         */
+        destroy() {
+            clearInterval(renderInterval);
+            if (widgetId !== null && window.turnstile) {
+                window.turnstile.remove(widgetId);
+            }
+        }
+    };
+}

package/dist/components/TurnstileWidget.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+	import { turnstileAction } from '../actions/action.js';
+	import type { TurnstileOptions } from '../types/types.js';
+
+	let {
+		sitekey,
+		action,
+		cData,
+		theme,
+		language,
+		tabindex,
+		retry,
+		"retry-interval": retryInterval,
+		size,
+		"response-field": responseField,
+		"response-field-name": responseFieldName,
+		appearance,
+		execution,
+		"refresh-expired": refreshExpired,
+		"refresh-timeout": refreshTimeout,
+		"feedback-enabled": feedbackEnabled,
+		"offlabel-show-privacy": offlabelShowPrivacy,
+		"offlabel-show-help": offlabelShowHelp,
+		ontoken,
+		onerror,
+		onexpire,
+		ontimeout,
+		onbeforeinteractive,
+		onafterinteractive,
+		onunsupported
+	}: Omit<
+		TurnstileOptions,
+		| 'callback'
+		| 'error-callback'
+		| 'expired-callback'
+		| 'timeout-callback'
+		| 'before-interactive-callback'
+		| 'after-interactive-callback'
+		| 'unsupported-callback'
+	> & {
+		ontoken?: (token: string) => void;
+		onerror?: (errorCode: string) => void;
+		onexpire?: () => void;
+		ontimeout?: () => void;
+		onbeforeinteractive?: () => void;
+		onafterinteractive?: () => void;
+		onunsupported?: () => void;
+	} = $props();
+
+	let options = $derived({
+		sitekey,
+		action,
+		cData,
+		theme,
+		language,
+		tabindex,
+		retry,
+		'retry-interval': retryInterval,
+		size,
+		'response-field': responseField,
+		'response-field-name': responseFieldName,
+		appearance,
+		execution,
+		'refresh-expired': refreshExpired,
+		'refresh-timeout': refreshTimeout,
+		'feedback-enabled': feedbackEnabled,
+		'offlabel-show-privacy': offlabelShowPrivacy,
+		'offlabel-show-help': offlabelShowHelp,
+		callback: ontoken,
+		'error-callback': onerror,
+		'expired-callback': onexpire,
+		'timeout-callback': ontimeout,
+		'before-interactive-callback': onbeforeinteractive,
+		'after-interactive-callback': onafterinteractive,
+		'unsupported-callback': onunsupported
+	} as TurnstileOptions);
+</script>
+
+<div use:turnstileAction={options}></div>

package/dist/components/TurnstileWidget.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { TurnstileOptions } from '../types/types.js';
+type $$ComponentProps = Omit<TurnstileOptions, 'callback' | 'error-callback' | 'expired-callback' | 'timeout-callback' | 'before-interactive-callback' | 'after-interactive-callback' | 'unsupported-callback'> & {
+    ontoken?: (token: string) => void;
+    onerror?: (errorCode: string) => void;
+    onexpire?: () => void;
+    ontimeout?: () => void;
+    onbeforeinteractive?: () => void;
+    onafterinteractive?: () => void;
+    onunsupported?: () => void;
+};
+declare const TurnstileWidget: import("svelte").Component<$$ComponentProps, {}, "">;
+type TurnstileWidget = ReturnType<typeof TurnstileWidget>;
+export default TurnstileWidget;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { default as TurnstileWidget } from './components/TurnstileWidget.svelte';
+export { turnstileAction } from './actions/action.ts';
+export type { TurnstileOptions } from './types/types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { default as TurnstileWidget } from './components/TurnstileWidget.svelte';
+export { turnstileAction } from "./actions/action.js";

package/dist/types/types.d.ts

@@ -0,0 +1,52 @@
+export interface TurnstileOptions {
+    /** Every widget has a sitekey. This sitekey is associated with the corresponding widget configuration and is created upon the widget creation. */
+    sitekey: string;
+    /** A customer value that can be used to differentiate widgets under the same sitekey in analytics and which is returned upon validation. This can only contain up to 32 alphanumeric characters including _ and -. */
+    action?: string;
+    /** A customer payload that can be used to attach customer data to the challenge throughout its issuance and which is returned upon validation. This can only contain up to 255 alphanumeric characters including _ and -. */
+    cData?: string;
+    /** Callback invoked upon successful completion of the challenge. The token is passed as an argument. */
+    callback?: (token: string) => void;
+    /** Callback invoked when there is an error (e.g. network error, challenge failed). */
+    "error-callback"?: (errorCode: string) => void;
+    /** Execution controls when to obtain the token of the widget and can be on "render" (default) or on "execute". */
+    execution?: "render" | "execute";
+    /** Callback invoked when the token expires and does not reset the widget. */
+    "expired-callback"?: () => void;
+    /** Callback invoked when an interactive challenge times out. */
+    "timeout-callback"?: () => void;
+    /** Callback invoked before an interactive challenge is shown. */
+    "before-interactive-callback"?: () => void;
+    /** Callback invoked after an interactive challenge has been completed or failed. */
+    "after-interactive-callback"?: () => void;
+    /** Callback invoked when a given client/browser is not supported by Turnstile. */
+    "unsupported-callback"?: () => void;
+    /** The widget theme. Can take the following values: "light", "dark", "auto". */
+    theme?: "auto" | "light" | "dark";
+    /** Language to display, must be either: "auto" (default) or an ISO 639-1 two-letter language code (e.g. "en") or language and country code (e.g. "en-US"). */
+    language?: "auto" | string;
+    /** The tabindex of Turnstile's iframe for accessibility purposes. The default value is 0. */
+    tabindex?: number;
+    /** Controls whether the widget should automatically retry to obtain a token if it did not succeed. Can take "auto" or "never". */
+    retry?: "auto" | "never";
+    /** When retry is set to "auto", retry-interval controls the time between retry attempts in milliseconds. Value must be a positive integer less than 900000, defaults to 8000. */
+    "retry-interval"?: number;
+    /** The widget size. Can take the following values: "normal", "flexible", "compact". */
+    size?: "normal" | "flexible" | "compact";
+    /** A boolean that controls if an input element with the response token should be created, defaults to true. */
+    "response-field"?: boolean;
+    /** Name of the input element field, defaults to "cf-turnstile-response". */
+    "response-field-name"?: string;
+    /** Appearance controls when the widget is visible. It can be "always", "execute", or "interaction-only". */
+    appearance?: "always" | "execute" | "interaction-only";
+    /** Controls the behavior when the token of a Turnstile widget expires. Can be "auto", "manual", or "never". */
+    "refresh-expired"?: "auto" | "manual" | "never";
+    /** Controls the behavior when an interactive challenge times out. Can be "auto", "manual", or "never". */
+    "refresh-timeout"?: "auto" | "manual" | "never";
+    /** Enables the feedback button. */
+    "feedback-enabled"?: boolean;
+    /** (Offlabel) Shows the privacy policy link. */
+    "offlabel-show-privacy"?: boolean;
+    /** (Offlabel) Shows the help link. */
+    "offlabel-show-help"?: boolean;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "turnstile-svelte",
+	"version": "1.0.0",
+	"description": "A Cloudflare Turnstile component and action for Svelte 5",
+	"author": "nstdev0",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": ""
+	},
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build && npm run prepack",
+		"preview": "vite preview",
+		"prepare": "svelte-kit sync || echo ''",
+		"prepack": "svelte-kit sync && svelte-package && publint",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+	},
+	"files": [
+		"dist",
+		"!dist/**/*.test.*",
+		"!dist/**/*.spec.*"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/kit": "^2.63.0",
+		"@sveltejs/package": "^2.5.8",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"publint": "^0.3.21",
+		"svelte": "^5.56.1",
+		"svelte-check": "^4.6.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.16"
+	},
+	"keywords": [
+		"svelte",
+		"svelte-5",
+		"cloudflare",
+		"turnstile",
+		"captcha",
+		"component",
+		"action"
+	]
+}