Widget configurations

Configure your Turnstile widget's appearance, behavior, and functionality using data attributes or JavaScript render parameters.

Turnstile widgets can be implemented using implicit or explicit rendering.

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>
	<div id="my-widget"></div>
	
	<script>
	window.onload = function() {
		turnstile.render('#my-widget', {
			sitekey: '<YOUR-SITE-KEY>',
			theme: 'light',
			callback: function(token) {
				console.log('Success:', token);
			}
		});
	};
	</script>

The Turnstile widget can have two different fixed sizes or a flexible width size when using the Managed or Non-Interactive modes.

• normal: The default size works well for most desktop and mobile layouts. Use this if you have adequate horizontal space on your website or form.
• flexible: Automatically adapts to the container width while maintaining minimum usability. Use this for responsive designs that need to work across all screen sizes.
• compact: Ideal for mobile interfaces, sidebars, or any space where horizontal space is limited. The compact widget is taller than normal to accommodate the smaller width.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'flexible'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'compact'
	});

Customize the widget's visual appearance to match your website's design.

• auto (default): Automatically matches the visitor's system theme preference. Auto is recommended for most implementations as it respects the visitor's preferences and provides the best accessibility experience.
• light: Light theme with bright colors and clear contrast. Light theme works best on bright backgrounds and provides high contrast for readability.
• dark: Dark theme optimized for dark interfaces. Dark theme is ideal for dark interfaces, gaming sites, or applications with dark color schemes.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="dark"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'light'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'dark'
	});

Control when the widget becomes visible to visitors using the appearance mode.

• always (default): The widget is always visible from page load. This is the best option for most implementations where you want your visitors to see the widget immediately as it provides clear visual feedback that security verification is in place.
• execute: The widget only becomes visible after the challenge begins. This is useful for when you need to control the timing of widget appearance, such as showing it only when a visitor starts filling out a form or selecting a submit button.
• interaction-only: The widget becomes visible only when visitor interaction is required and provides the cleanest visitor experience. Most visitors will never see the widget, but suspected bots will encounter the interactive challenge.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="execute"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="interaction-only"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'execute'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'interaction-only'
	});

Control when the challenge runs and a token is generated.

• render (default): The challenge runs automatically after calling the render() function and provides immediate protection as soon as the widget loads. The challenge runs in the background while the page loads, ensuring the token is ready when the visitor submits data.

• execute: The challenge runs after calling the turnstile.execute() function separately and gives you precise control over when verification occurs. This option is useful for multi-step forms, conditional verification, or when you want to defer the challenge until the visitor actually attempts to submit data. This can improve page load performance and visitor experience by only running verification when needed.

  Common scenarios

  • Multi-step forms: Run verification only on the final step.
  • Conditional protection: Only verify visitors who meet certain criteria.
  • Performance optimization: Defer verification to reduce initial page load time.
  • User-triggered verification: Let visitors manually start the verification process.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-execution="execute"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		execution: 'execute'
	});

	turnstile.execute('#widget-container');

Set the language for the widget interface.

• auto (default): Uses the visitor's browser language preference.
• Specific language codes: ISO 639-1 two-letter codes, such as es, fr, de.
• Language and region: Combined codes for regional variants, such as en-US, es-MX, pt-BR.

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="es"></div>

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="en-US"></div>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		language: 'es'
	});

Handle widget events with callbacks.

• callback: Triggered when the challenge is successfully completed.
• error-callback: Triggered when an error occurs during the challenge.
• expired-callback: Triggered when a token expires (before timeout).
• timeout-callback: Triggered when an interactive challenge times out.

The success callback receives a token that must be validated on your server using the Siteverify API. Tokens are single-use and expire after 300 seconds (five minutes).

	<div class="cf-turnstile"
		data-sitekey="<YOUR-SITE-KEY>"
		data-callback="onSuccess"
		data-error-callback="onError"
		data-expired-callback="onExpired"
		data-timeout-callback="onTimeout"></div>
	<script>
	function onSuccess(token) {
	console.log('Challenge Success:', token);
	}
	function onError(errorCode) {
	console.log('Challenge Error:', errorCode);
	}
	function onExpired() {
	console.log('Token expired');
	}
	function onTimeout() {
	console.log('Challenge timed out');
	}
	</script>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		callback: function(token) {
			console.log('Challenge Success:', token);
		},
		'error-callback': function(errorCode) {
			console.log('Challenge Error:', errorCode);
		},
		'expired-callback': function() {
			console.log('Token expired');
		},
		'timeout-callback': function() {
			console.log('Challenge timed out');
		}
	});

• Always implement the success callback to handle the token and proceed with form submission or next steps.
• Use error callbacks for graceful error handling and visitor feedback.
• Monitor expired tokens to refresh challenges before they become invalid.
• Handle timeouts to guide visitors through challenge resolution.

Control how Turnstile handles failed challenges.

• auto (default): Automatically retries failed challenges. Auto retry provides better visitor experience by automatically recovering from temporary network issues or processing errors.
• never: Disables automatic retry. This requires manual intervention and gives you full control over error handling in applications that need custom retry logic.
• retry-interval: Controls the time between retry attempts (default: 8000ms) and lets you balance between quick recovery and server load.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry="never"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry-interval="0000"></div>

Control how Turnstile handles token expiration and interactive timeouts.

• refresh-expired: Controls behavior when tokens expire (auto, manual, never).
• refresh-timeout: Controls behavior when interactive challenges timeout (auto, manual, never).

• auto refresh provides seamless visitor experience but uses more resources.
• manual refresh gives visitors control but requires them to take action.
• never refresh requires your application to handle all refresh logic.

Different strategies can be used for token expiration versus interactive timeouts based on your visitor experience requirements.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-expired="manual"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-timeout="auto"></div>

Add custom identifiers and data to your challenges.

• action: A custom identifier for analytics and differentiation (maximum 32 characters).
• cData: Custom payload data returned during validation (maximum 255 characters).

• Action tracking: Differentiate between login, signup, contact forms, and more. in your analytics.
• Visitor context: Pass visitor IDs, session information, or other contextual data.
• A/B testing: Track different widget configurations or page variants.
• Fraud detection: Include additional context for risk assessment.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-action="login"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-cdata="user-cdata"></div>

Configure how Turnstile integrates with HTML forms.

When enabled, Turnstile automatically creates a hidden <input> element with the verification token. This gets submitted along with your other form data, making server-side validation straightforward.

• response-field: Determines whether to create a hidden form field with the token (default: true)
• response-field-name: Custom name for the hidden form field (default: cf-turnstile-response)

• Automatic form integration means that the token is included when the form is submitted, requiring no additional JavaScript.
• Custom field names helps avoid conflicts with existing form fields.
• Disabled response fields give you full control over token handling for complex form scenarios.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field-name="turnstile-token"></div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field="false"></div>

<div style="max-width: 500px;">
  <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible" data-theme="auto"></div>
</div>

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact" data-theme="light" data-language="en">
</div>