我的书签
添加书签
移除书签Widget configurations·续
Auto retry (default)html
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
Disable retryhtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry="never"></div>
Custom retry interval (8000ms default)html
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry-interval="0000"></div>
Refresh behavior
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).
Benefits
autorefresh provides seamless visitor experience but uses more resources.manualrefresh gives visitors control but requires them to take action.neverrefresh 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.
Auto refresh expired tokens (default)html
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
Manual refreshhtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-expired="manual"></div>
Auto refresh timeouts (default for Managed mode)html
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-timeout="auto"></div>
Custom data
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).
Use cases
- 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.
Caution
Both action and cData fields only accept alphanumeric characters, underscores (_), and hyphens (-).
Add custom action identifierhtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-action="login"></div>
Add custom data payloadhtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-cdata="user-cdata"></div>
Form integration
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)
Benefits
- 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.
Custom response field namehtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field-name="turnstile-token"></div>
Disable response fieldhtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field="false"></div>
Complete configuration reference
| JavaScript Render Parameters | Data Attribute | Description |
|---|---|---|
sitekey |
data-sitekey |
Every widget has a sitekey. This sitekey is associated with the corresponding widget configuration and is created upon the widget creation. |
action |
data-action |
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 -. |
cData |
data-cdata |
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 -. |
callback |
data-callback |
A JavaScript callback invoked upon success of the challenge. The callback is passed a token that can be validated. |
error-callback |
data-error-callback |
A JavaScript callback invoked when there is an error (e.g. network error or the challenge failed). Refer to Client-side errors. |
execution |
data-execution |
Execution controls when to obtain the token of the widget and can be on render (default) or on execute. Refer to Execution Modes for more information. |
expired-callback |
data-expired-callback |
A JavaScript callback invoked when the token expires and does not reset the widget. |
before-interactive-callback |
data-before-interactive-callback |
A JavaScript callback invoked before the challenge enters interactive mode. |
after-interactive-callback |
data-after-interactive-callback |
A JavaScript callback invoked when challenge has left interactive mode. |
unsupported-callback |
data-unsupported-callback |
A JavaScript callback invoked when a given client/browser is not supported by Turnstile. |
theme |
data-theme |
The widget theme. Can take the following values: light, dark, auto. <br><br>The default is auto, which respects the visitor preference. This can be forced to light or dark by setting the theme accordingly. |
language |
data-language |
Language to display, must be either: auto (default) to use the language that the visitor has chosen, or an ISO 639-1 two-letter language code (e.g. en) or language and country code (e.g. en-US). Refer to the list of supported languages for more information. |
tabindex |
data-tabindex |
The tabindex of Turnstile's iframe for accessibility purposes. The default value is 0. |
timeout-callback |
data-timeout-callback |
A JavaScript callback invoked when the challenge presents an interactive challenge but was not solved within a given time. A callback will reset the widget to allow a visitor to solve the challenge again. |
response-field |
data-response-field |
A boolean that controls if an input element with the response token is created, defaults to true. |
response-field-name |
data-response-field-name |
Name of the input element, defaults to cf-turnstile-response. |
size |
data-size |
The widget size. Can take the following values: normal, flexible, compact. |
retry |
data-retry |
Controls whether the widget should automatically retry to obtain a token if it did not succeed. The default is auto, which will retry automatically. This can be set to never to disable retry on failure. |
retry-interval |
data-retry-interval |
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. |
refresh-expired |
data-refresh-expired |
Automatically refreshes the token when it expires. Can take auto, manual, or never, defaults to auto. |
refresh-timeout |
data-refresh-timeout |
Controls whether the widget should automatically refresh upon entering an interactive challenge and observing a timeout. Can take auto (automatically refreshes upon encountering an interactive timeout), manual (prompts the visitor to manually refresh) or never (will show a timeout), defaults to auto. Only applies to widgets of Managed mode. |
appearance |
data-appearance |
Appearance controls when the widget is visible. It can be always (default), execute, or interaction-only. Refer to Appearance modes for more information. |
feedback-enabled |
data-feedback-enabled |
Allows Cloudflare to gather visitor feedback upon widget failure. It can be true (default) or false. |
offlabel-show-privacy |
data-offlabel-show-privacy |
Displays privacy link for unbranded Turnstile widgets. Can be true (default) or false. |
offlabel-show-help |
data-offlabel-show-help |
Displays help link for unbranded Turnstile widgets. Can be true (default) or false. |
Examples
Responsive design widgethtml
<div style="max-width: 500px;">
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible" data-theme="auto"></div>
</div>
Mobile-optimized compact widgethtml
<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact" data-theme="light" data-language="en">
</div>
Was this helpful?
YesNo
On this page
Docs{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/#page","headline":"Widget configurations","description":"Configure widget appearance, language, and callback functions.","url":"https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/","inLanguage":"en","image":"https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/widget-configurations/og.png?v=200be8a9b419a2f9","dateModified":"2026-06-28","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["JavaScript"]}
description: Implement Turnstile in native mobile applications. title: Mobile implementation image: https://developers.cloudflare.com/turnstile/get-started/mobile-implementation/og.png?v=ed9777c0d868fc50
Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/turnstile/llms.txt
Use this file to discover all available pages before exploring further.
