### Install Svelte Turnstile

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Install the svelte-turnstile package as a development dependency using npm.

```sh
npm install svelte-turnstile -D
```

--------------------------------

### Svelte Turnstile Component Usage

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Demonstrates how to install and use the svelte-turnstile component in a Svelte application. It requires a siteKey obtained from Cloudflare.

```APIDOC
## Installation

```sh
npm install svelte-turnstile -D
```

## Basic Usage

The `Turnstile` component requires a `siteKey` prop. This key is obtained from your Cloudflare dashboard.

### Component

```svelte
<script>
	import { Turnstile } from 'svelte-turnstile';
</script>

<Turnstile siteKey="SITE_KEY" />
```

### Props

| Prop                | Type                                                 | Description                                                                                    | Required |
| ------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------- |
| `siteKey`           | `string`                                             | sitekey for your website                                                                       | ✅       |
| `theme`             | `'light' | 'dark' | 'auto'`                        | colour theme of the widget (defaults to `auto`)                                                |          |
| `size`              | `'normal' | 'flexible' | 'invisible' | 'compact'` | size of the widget (defaults to `normal`)                                                      |          |
| `action`            | `string`                                             | A string that can be used to differentiate widgets, returned on validation                     |          |
| `cData`             | `string`                                             | A string that can attach customer data to a challange, returned on validation                  |          |
| `tabIndex`          | `number`                                             | Used for accessibility (defaults to `0`)                                                       |          |
| `responseField`     | `boolean`                                            | if true the response token will be a property on the form data (default `true`)                |          |
| `responseFieldName` | `string`                                             | the `name` of the input which will appear on the form data (default `cf-turnstile-response`)   |          |
| `retry`             | `'auto' | 'never'`                                  | should the widget automatically retry to obtain a token if it did not succeed (default `auto`) |          |
| `retryInterval`     | `number`                                             | if `retry` is true, this controls the time between attempts in milliseconds (default `8000`)   |          |
| `language`          | `SupportedLanguage | 'auto'`                        | the language turnstile should use (default `auto`)                                             |          |
| `execution`         | `'render' | 'execute'`                              | controls when to obtain the token of the widget (default `render`)                             |          |
| `appearance`        | `'always' | 'execute' | 'interaction-only'`        | controls when the widget is visible. (default `always`)                                        |          |

For more information about some of the props and a list of `SupportedLanguage`'s [checkout the Cloudflare Documentation](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#configurations).

### Deprecated Props

- `forms` renamed to `responseField`
- `formsField` renamed to `responseFieldName`
```

--------------------------------

### Validate Turnstile Token Server-Side

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Use this function to verify the Turnstile token on your backend. It requires the token and your secret key. Ensure your secret key is handled securely, for example, using environment variables.

```typescript
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 {
		// Return the status
		success: data.success,

		// Return the first error if it exists
		error: data['error-codes']?.length ? data['error-codes'][0] : null,
	};
}
```

--------------------------------

### SvelteKit Server Load and Actions for Login

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Handles form loading and submission on the server. It validates the Turnstile token using a secret key before processing the form data.

```javascript
import {
	fail,
	message,
	setError,
	superValidate
} from 'sveltekit-superforms';
import {
	zod
} from 'sveltekit-superforms/adapters';
import {
	schema
} from './schema.ts';

export const load = async () => {
	const form = await superValidate(zod(schema));
	return { form };
};

export const actions = {
	default: async ({ request }) => {
		const form = await superValidate(request, zod(schema));
		if (!form.valid) return fail(400, {
			form
		});

		const {
			success
		} = await validateToken(
			form.data['cf-turnstile-response'],
			SECRET_KEY,
		);

		if (!success) {
			return setError(
				form,
				'cf-turnstile-response',
				'Invalid turnstile, please try again',
			);
		}

		return message(form, 'Success!');
	},
};
```

--------------------------------

### Use Cloudflare Test Site Keys

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Utilize these predefined test site keys from Cloudflare to simulate different Turnstile scenarios during development. This allows testing of always-passing, always-blocking, and interactive challenge modes without affecting production.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';

  // Test Site Keys
  const ALWAYS_PASS = '1x00000000000000000000AA';
  const ALWAYS_BLOCK = '2x00000000000000000000AB';
  const FORCE_INTERACTIVE = '3x00000000000000000000FF';

  // Test Secret Keys (for server-side validation)
  // Always Pass: '1x0000000000000000000000000000000AA'
  // Always Fail: '2x0000000000000000000000000000000AA'
  // Token Spent: '3x0000000000000000000000000000000AA'
</script>

<Turnstile siteKey={ALWAYS_PASS} />
```

--------------------------------

### Basic Turnstile Component

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Render the Turnstile verification widget with automatic script loading and token management. Ensure you replace 'YOUR_SITE_KEY' with your actual Cloudflare Turnstile site key.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';
</script>

<Turnstile siteKey="YOUR_SITE_KEY" />
```

--------------------------------

### Basic Svelte Turnstile Integration

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Import and use the Turnstile component in your Svelte application. Ensure you replace 'SITE_KEY' with your actual Cloudflare Turnstile site key.

```svelte
<script>
	import { Turnstile } from 'svelte-turnstile';
</script>

<Turnstile siteKey="SITE_KEY" />
```

--------------------------------

### SvelteKit Login Form with Turnstile

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Integrate Turnstile into a SvelteKit login form using form actions. The `cf-turnstile-response` is automatically submitted with the form data. The server-side action then calls the `validateToken` function.

```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>
```

```javascript
// Copy and paste the validateToken function from above here

export const actions = {
	default: async ({ request }) => {
		const data = await request.formData();

		const token = data.get('cf-turnstile-response'); // if you edited the formsField option change this
		const SECRET_KEY = '...'; // you should use $env module for secrets

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

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

		// do something, the captcha is valid!
	},
};
```

--------------------------------

### Turnstile with Theme and Size Options

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Customize the appearance of the Turnstile widget using the 'theme' (light/dark/auto) and 'size' (normal/flexible/compact/invisible) props. The 'tabIndex' prop can be used to control focus order.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';
</script>

<Turnstile
  siteKey="YOUR_SITE_KEY"
  theme="dark"
  size="compact"
  tabIndex={0}
/>
```

--------------------------------

### Configure Turnstile Component Properties

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Use this snippet to configure various properties of the Turnstile component, such as theme, size, execution mode, appearance, retry behavior, language, action, custom data, and event callbacks. Ensure you replace 'YOUR_SITE_KEY' with your actual Cloudflare site key.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';
</script>

<Turnstile
  siteKey="YOUR_SITE_KEY"
  theme="auto"
  size="flexible"
  execution="render"
  appearance="always"
  retry="auto"
  retryInterval={8000}
  language="en"
  action="login"
  cData="user-session-123"
  tabIndex={0}
  on:callback={(e) => console.log('Token:', e.detail.token)}
  on:error={(e) => console.error('Error:', e.detail.code)}
  on:before-interactive={() => console.log('Challenge starting')}
  on:after-interactive={() => console.log('Challenge completed')}
  on:unsupported={() => console.log('Browser not supported')}
/>
```

--------------------------------

### Manually Resetting Svelte Turnstile

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Demonstrates how to manually reset the Turnstile widget by binding to the 'reset' prop and calling it from a button click.

```svelte
<script lang="ts">
	let reset = $state<() => void>();
</script>

<button onclick={() => reset?.()}> Reset </button>

<Turnstile bind:reset />
```

--------------------------------

### Turnstile with Event Callbacks

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Handle various Turnstile verification events such as successful verification, errors, timeouts, and token expiration using Svelte's event handling. The 'callback' event provides the verification token and pre-clearance status.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';

  let token = '';

  function handleCallback(event) {
    token = event.detail.token;
    console.log('Verification successful:', token);
    console.log('Pre-clearance obtained:', event.detail.preClearanceObtained);
  }

  function handleError(event) {
    console.error('Turnstile error:', event.detail.code);
  }

  function handleExpired() {
    console.log('Token expired');
    token = '';
  }

  function handleTimeout() {
    console.log('Challenge timed out');
  }
</script>

<Turnstile
  siteKey="YOUR_SITE_KEY"
  on:callback={handleCallback}
  on:error={handleError}
  on:expired={handleExpired}
  on:timeout={handleTimeout}
/>
```

--------------------------------

### SvelteKit Form Actions with Turnstile

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Use this for basic server-side validation of Turnstile tokens within SvelteKit's form actions. Ensure your TURNSTILE_SECRET_KEY is set in your environment variables.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';
  import { enhance } from '$app/forms';

  export let form;
  let reset;
</script>

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

<form method="POST" use:enhance>
  <input type="email" name="email" placeholder="Email" required />

  <Turnstile siteKey="YOUR_SITE_KEY" theme="dark" bind:reset />

  <button type="submit">Submit</button>
  <button type="button" on:click={() => reset?.()}>Reset</button>
</form>

{#if form?.valid}
  <p class="success">Form submitted successfully!</p>
{/if}
```

```typescript
import type { Actions } from './$types';

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,
  };
}

export const actions: Actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    const token = data.get('cf-turnstile-response') as string;
    const SECRET_KEY = process.env.TURNSTILE_SECRET_KEY;

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

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

    // Process form data here
    return { valid: true };
  },
};
```

--------------------------------

### HTML Form Integration

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Integrate Turnstile with traditional HTML forms to automatically include the verification token as a form field. Set 'responseField' to true and optionally specify 'responseFieldName'.

```svelte
<script>
  import { Turnstile } from 'svelte-turnstile';
</script>

<form method="POST" action="/login">
  <input type="text" name="username" placeholder="Username" />
  <input type="password" name="password" placeholder="Password" />

  <!-- Token automatically added as 'cf-turnstile-response' form field -->
  <Turnstile
    siteKey="YOUR_SITE_KEY"
    responseField={true}
    responseFieldName="cf-turnstile-response"
  />

  <button type="submit">Login</button>
</form>
```

--------------------------------

### Zod Schema for Login Form

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Defines the schema for the login form using Zod, including the required 'cf-turnstile-response' field.

```typescript
import {
	z
} from "zod";

export const schema = z.object({
	..., // other fields
    'cf-turnstile-response': z.string().nonempty('Please complete turnstile')
});
```

--------------------------------

### Svelte Component for Login Form with Turnstile

Source: https://github.com/ghostdevv/svelte-turnstile/blob/main/README.md

Integrates Svelte Turnstile into a Svelte component using SvelteKit Superforms. It binds to the reset function and captures the Turnstile token on callback.

```svelte
<script lang="ts">
	import {
		zodClient
	} from 'sveltekit-superforms/adapters';
	import {
		superForm
	} from 'sveltekit-superforms';
	import {
		Turnstile
	} from 'svelte-turnstile';
	import {
		schema
	} from './schema.ts';

	let {
		data
	} = $props();

	// Call this to reset the turnstile
	let reset = $state<() => void>();

	const {
		form,
		enhance,
		message
	} = superForm(data.form, {
		validators: zodClient(schema),
		onUpdated() {
			// When the form is updated, we reset the turnstile
			reset?.();
		},
	});
</script>

<form method="POST" use:enhance>
	<Turnstile
		siteKey={PUBLIC_TURNSTILE_SITE_KEY}
		bind:reset
		on:callback={(event) => {
			// Required when using client side validation
			$form['cf-turnstile-response'] = event.detail.token;
		}} />
</form>
```

--------------------------------

### Superforms Integration with Turnstile Component

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Integrate Turnstile within a sveltekit-superforms form. The `on:callback` event handler updates the form data with the Turnstile token, and `onUpdated` resets the widget.

```svelte
<script lang="ts">
  import { zodClient } from 'sveltekit-superforms/adapters';
  import { superForm } from 'sveltekit-superforms';
  import { Turnstile } from 'svelte-turnstile';
  import { schema } from './schema';

  export let data;

  let reset: (() => void) | undefined;

  const { form, errors, message, enhance } = superForm(data.form, {
    validators: zodClient(schema),
    onUpdated() {
      // Reset turnstile when form is updated
      reset?.();
    },
  });
</script>

<form method="POST" use:enhance>
  <label>
    Name
    <input type="text" name="name" bind:value={$form.name} />
    {#if $errors.name}<span class="error">{$errors.name}</span>{/if}
  </label>

  <label>
    Email
    <input type="email" name="email" bind:value={$form.email} />
    {#if $errors.email}<span class="error">{$errors.email}</span>{/if}
  </label>

  <Turnstile
    siteKey="YOUR_SITE_KEY"
    bind:reset
    on:callback={(event) => {
      $form['cf-turnstile-response'] = event.detail.token;
    }}
  />
  {#if $errors['cf-turnstile-response']}
    <span class="error">{$errors['cf-turnstile-response']}</span>
  {/if}

  <button type="submit">Submit</button>
</form>

{#if $message}
  <p class="success">{$message}</p>
{/if}
```

--------------------------------

### TypeScript Types for Svelte Turnstile

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Import and utilize TypeScript types provided by the svelte-turnstile library for Turnstile options like theme, size, and language. This enhances type safety and autocompletion during development.

```typescript
import type {
  TurnstileTheme,
  TurnstileSize,
  TurnstileLanguage
} from 'svelte-turnstile';

// Event types
interface CallbackEvent {
  token: string;
  preClearanceObtained: boolean;
}

interface ErrorEvent {
  code: string;
}
```

--------------------------------

### Superforms Server-Side Validation with Turnstile

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Handle Turnstile token validation on the server using sveltekit-superforms. This function validates the token against the Turnstile API and returns success or error messages.

```typescript
import { fail, message, setError, superValidate } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { schema } from './schema';

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 = await response.json();
  return { success: data.success };
}

export const load = async () => {
  const form = await superValidate(zod(schema));
  return { form };
};

export const actions = {
  default: async ({ request }) => {
    const form = await superValidate(request, zod(schema));
    if (!form.valid) return fail(400, { form });

    const { success } = await validateToken(
      form.data['cf-turnstile-response'],
      process.env.TURNSTILE_SECRET_KEY,
    );

    if (!success) {
      return setError(
        form,
        'cf-turnstile-response',
        'Invalid turnstile, please try again',
      );
    }

    return message(form, 'Form submitted successfully!');
  },
};
```

--------------------------------

### Superforms Integration with Turnstile Schema

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Define a Zod schema for Turnstile validation when using sveltekit-superforms. This ensures the Turnstile token is present and valid.

```typescript
import { z } from 'zod';

export const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  email: z.string().email('Invalid email address'),
  'cf-turnstile-response': z.string().nonempty('Please complete turnstile'),
});
```

--------------------------------

### Server-Side Token Validation

Source: https://context7.com/ghostdevv/svelte-turnstile/llms.txt

Validate the Turnstile token on your server by making a POST request to Cloudflare's siteverify endpoint. This function returns the validation success status and any error codes.

```typescript
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,
  };
}

// Usage
const { success, error } = await validateToken(token, 'YOUR_SECRET_KEY');
if (!success) {
  console.error('Validation failed:', error);
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.