Turnstile widgets
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.
Each widget gets its own unique sitekey and secret key pair, and options for configurations.
| Component | Description |
|---|---|
| Sitekey | Public key used to invoke the Turnstile widget on your site. |
| Secret key | Private key used for server-side token validation. |
| Configurations | Mode, hostnames, appearance settings, and other options. |
The available modes for Turnstile widgets are Managed, Non-Interactive, and Invisible.
Managed mode is fully managed by Cloudflare. It automatically chooses the appropriate action based on client-side signals and risk levels. Cloudflare uses 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 visitor will be prompted to select a box. There will be no images or text to decipher.
Managed mode is ideal for users who want a simple configuration without needing to fine-tune the widget's behavior.
Visitors will see a widget with a loading spinner while the challenges run in their browsers. Unlike managed mode, visitors will never be required or prompted to interact with the widget.
Non-Interactive mode is ideal for users who want to prioritize visitor experience and do not want to add any friction on their website with a Turnstile interaction.
Invisible mode is similar to Non-Interactive mode where visitors will never interact with the Turnstile widget. Visitors will also not see a widget or any indication that an invisible browser challenge is in progress.
Invisible mode is ideal for users who want to prioritize visitor and visual experience on their website.
Widgets can be implemented in normal, flexible, or compact sizes.
Refer to Widget configurations for detailed configuration options and code examples.
Turnstile widgets support multiple appearance modes and themes to match your website's design.
Refer to Widget configurations for implementation details.
- Loading: Widget is processing the challenge.
- Interaction: Visitor needs to check the box (Managed mode only).
- Success: The Challenge was completed successfully.
When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can follow the troubleshooting guidelines from the widget or refresh the page to retry the challenge.
When the visitor is presented with a checkbox but does not interact with it for an extended period of time. The challenge must be reissued by reloading the page or the widget.
When the verification was completed but no further action has been taken, the challenge outcome will no longer be valid. For example, if a Turnstile widget is on a login page and the Turnstile successfully ran, but the visitor did not log in for an extended period of time, the challenge must be reissued by reloading the page or the widget.
Visitors with outdated browsers or unsupported browsers will encounter this widget state.
Refer to Supported browsers for more information regarding supported browsers.
Was this helpful?
- Resources
- API
- New to Cloudflare?
- Directory
- Sponsorships
- Open Source
- Support
- Help Center
- System Status
- Compliance
- GDPR
- Company
- cloudflare.com
- Our team
- Careers
- © 2025 Cloudflare, Inc.
- Privacy Policy
- Terms of Use
- Report Security Issues
- Trademark
-
