svelte-turnstile

To prevent forgery, you must validate the Turnstile token on your server using Cloudflare's siteverify endpoint.

If using a standard HTML form, the token is available via the responseFieldName (default: cf-turnstile-response). If using client-side logic, capture the token via the on:callback event.

interface TokenValidateResponse {
	'error-codes': string[];
	success: boolean;
	action: string;
	cdata: string;
}

async function validateToken(token: string, secret: string) {
	const response = await fetch(
		'https://challenges.cloudflare.com/turnstile/v0/siteverify',
		{
			method: 'POST',
			headers: {
				'content-type': 'application/json',
			},
			body: JSON.stringify({
				response: token,
				secret: secret,
			}),
		},
	);

	const data: TokenValidateResponse = await response.json();

	return {
		success: data.success,
		error: data['error-codes']?.length ? data['error-codes'][0] : null,
	};
}

In SvelteKit, you can use Turnstile within a form and validate the token in a server-side action.

Client Side (routes/login/+page.svelte):

<script>
	import { Turnstile } from 'svelte-turnstile';
	let { form } = $props();
</script>

{#if form?.error}
	<p>{form?.error}</p>
{/if}

<form method="POST" action="/login">
	<Turnstile siteKey="SITE_KEY" theme="dark" />
</form>

Server Side (routes/login/+page.server.js):

// Use the validateToken function defined in the documentation
export const actions = {
	default: async ({ request }) => {
		const data = await request.formData();
		const token = data.get('cf-turnstile-response');
		const SECRET_KEY = '...'; // Use environment variables for secrets

		const { success, error } = await validateToken(token, SECRET_KEY);

		if (!success) {
			return { error: error || 'Invalid CAPTCHA' };
		}

		// Proceed with logic if valid
	},
};

The Turnstile component accepts several props to customize its behavior and appearance:

Note on Deprecated Props:

• Use responseField instead of forms.
• Use responseFieldName instead of formsField.

The Turnstile component emits several events to communicate widget state:

Note on Deprecated Events:

• Use on:callback instead of on:turnstile-callback.
• Use on:error instead of on:turnstile-error.
• Use on:timeout instead of on:turnstile-timeout.
• Use on:expired instead of on:turnstile-expired.

The svelte-turnstile component emits several events that allow you to react to the lifecycle of the Cloudflare Turnstile challenge.

Note on Deprecated Events: Several older event names are deprecated. You should use the new event names listed below:

• Use callback instead of turnstile-callback.
• Use error instead of turnstile-error.
• Use expired instead of turnstile-expired.
• Use timeout instead of turnstile-timeout.

Available Events:

// Example of listening to events in a Svelte component
<Turnstile 
  on:callback={(e) => console.log('Token:', e.detail.token)} 
  on:error={(e) => console.error('Error code:', e.detail.code)} 
/>