Widget
Every instance of Turnstile belongs to a Turnstile widget. It is configured on a per-widget level. Every widget has a mode, a label, a sitekey, and a secret key.
The 3 modes for Turnstile are Managed, Non-Interactive, and Invisible.
Refer to appearance modes to configure whether to have the widget be always visible or visible only when interaction is required.
Widgets can be implemented in normal, flexible, or compact sizes.
| Size | Width | Height |
|---|---|---|
| Normal | 300px | 65px |
| Flexible | 100% (min: 300px) | 65px |
| Compact | 150px | 140px |
Refer to widget sizes for an example on how to configure flexible or compact mode.
This mode is fully managed by Cloudflare. It automatically chooses the appropriate action based on various signals and risk levels. Cloudflare will use the information from the visitor to decide if an interactive challenge should be used. Turnstile will only require interaction if a further check is necessary to verify that the visitor is human. When an interaction is required, the user will be prompted to check a box (no images or text to decipher). This managed mode is ideal for users who want a simple configuration without needing to fine-tune the behavior.
You can configure the Turnstile widget in compact mode, which functions in the same way as a Managed widget.
Visitors will see a widget with a loading bar while the browser challenges run. Unlike managed mode, visitors will never be required or prompted to interact with the widget. This mode is ideal for users who want to prioritize visitor experience and do not want to add any friction with a Turnstile interaction.
This mode is similar to non-interactive mode where visitors will never interact with the Turnstile widget. Visitors will not see a widget or any indication that an invisible browser challenge is in progress. Invisible challenges should take a few seconds to complete.
When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can refresh and retry the challenge. If the error persists, they can submit a feedback form by selecting Send feedback on the widget.
Refer to Feedback reports for more information.
When the challenge is not solved for an extended period of time, it must be issued again by reloading the page or the widget.
The widget expires when a token was issued but the user did not solve the challenge after an extended period of time. The page or widget must be reloaded.
Visitors with outdated browsers or unsupported browsers will encouter this widget state. Refer to Supported browsers for more information regarding supported browsers.