You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 <GlossaryTooltipterm="sitekey">sitekey</GlossaryTooltip>, and a <GlossaryTooltipterm="secret key">secret key</GlossaryTooltip>.
11
11
12
-
The 3 modes for Turnstile are **Managed**, **Non-Interactive**, and **Invisible**.
12
+
## Widget components
13
13
14
-
Refer to [appearance modes](/turnstile/get-started/client-side-rendering/#appearance-modes) to configure whether to have the widget be always visible or visible only when interaction is required, and to customize your widget theme between automatic, light, or dark mode.
14
+
-**Sitekey**: Public key used to invoke the Turnstile widget on your site
15
+
-**Secret key**: Private key used for server-side verification (keep secure)
15
16
16
-
Widgets can be implemented in normal, flexible, or compact sizes.
17
-
18
-
<Renderfile="widget-size" />
19
-
20
-
Refer to [widget sizes](/turnstile/get-started/client-side-rendering/#widget-size) for an example on how to configure flexible or compact mode.
21
-
22
-
:::note[Offlabel]
23
-
Customers with Enterprise Bot Management and Enterprise Turnstile have the ability to remove the Cloudflare branding and customize a specific Turnstile widget via the [API](/api/resources/turnstile/subresources/widgets/methods/update/).
24
-
:::
25
-
26
-
## Availability
27
-
28
-
Free users are limited to 20 widgets per account.
29
-
30
-
Customers with Enterprise Bot Management and Enterprise Turnstile can have this limit increased. Contact your account team to increase your widget limit.
17
+
Each widget gets its own unique sitekey and secret key pair.
31
18
32
-
## Widget types
19
+
## Widget modes
33
20
34
-
### Managed (recommended)
21
+
The available modes for Turnstile widgets are **Managed**, **Non-Interactive**, and **Invisible**.
35
22
36
-
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.
23
+
### Managed mode (recommended)
37
24
38
-
#### Light mode
25
+
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 user will be prompted to select a box. There will be no images or text to decipher.
43
28
44
-
#### Dark mode
29
+
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 bar while the challenges run in their browsers. Unlike managed mode, visitors will never be required or prompted to interact with the widget.
51
34
52
-
You can configure the Turnstile widget in compact mode, which functions in the same way as a Managed widget.
35
+
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.
57
40
58
-
#### Dark mode
41
+
Invisible mode is ideal for users who want to prioritize visitor and visual experience on their website.
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.
65
-
66
-
#### Light mode
43
+
---
67
44
68
-
Widgets can be implemented in normal, flexible, or compact sizes.
75
50
76
-
### Invisible
51
+
Refer to [Widget configurations](/turnstile/get-started/widget-configurations/) for detailed configuration options and code examples.
77
52
78
-
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.
53
+
### Appearance and themes
79
54
80
-
## Error states
55
+
Turnstile widgets support multiple appearance modes and themes to match your website's design. Refer to [Widget configurations](/turnstile/get-started/widget-configurations/) for implementation details.
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.
61
+
### Normal operation states
87
62
88
-
Refer to [Feedback reports](/turnstile/troubleshooting/feedback-reports) for more information.
63
+
-**Loading**: Widget is processing the challenge
64
+
-**Interactive**: User needs to check the box (Managed mode only)
When the challenge is not solved for an extended period of time, it must be issued again by reloading the page or the widget.
71
+
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.
99
76
100
-
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.
77
+
#### Challenge timed out
101
78
102
-
### Outdated or unsupported browser
79
+
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](/cloudflare-challenges/#browser-support) for more information regarding supported browsers.
0 commit comments