Props
These are the props you can pass to the Turnstile component.
| Prop | Type | Description |
|---|---|---|
siteKey | string | Your sitekey key, get one from here. |
options | object | Widget render parameters. More info below. |
scriptOptions | object | You can customize the injected script tag with this prop. It allows you to add "async", "defer", "nonce" attributes to the script tag. You can also control whether the injected script will be added to the document body or head with appendTo attribute. More info below. |
onWidgetLoad | function | Callback invoked after a successful render of the widget. The callback is passed the widget ID. It does not trigger when the widget is reset. |
onSuccess | function | Callback invoked upon success of the challenge. The callback is passed a token that can be validated. |
onExpire | function | Callback invoked when a challenge expires. Read the Cloudflare docs for more info about handling expired widgets. |
onError | function | Callback invoked when there is an error (e.g. network error or the challenge failed). Refer to Client-side errors. |
onBeforeInteractive | function | Callback invoked before the challenge enters interactive mode. |
onAfterInteractive | function | Callback invoked when challenge has left interactive mode. |
onUnsupported | function | Callback invoked when a given client/browser is not supported by Turnstile. |
onTimeout | function | Callback that is invoked when the Turnstile widget times out. |
as | string | Define the HTML tag of the widget container. Default to "div". |
injectScript | boolean | Controls if the script is automatically injected or not. If you want to inject the script manually, set this property to false. Default to true. |
onLoadScript | function | Callback invoked when the script is loaded. |
You can pass any valid HTML prop such as className, id, or style, based on the as prop.
Render Options
| Option | Type | Default | Description |
|---|---|---|---|
action | string | undefined | 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 | string | undefined | 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 -. |
theme | string | "auto" | The widget theme. You can choose between "light", "dark" or "auto". |
language | string | "auto" | 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 | number | 0 | The tabindex of Turnstile’s iframe for accessibility purposes. |
responseField | boolean | true | A boolean that controls if an input element with the response token is created. |
responseFieldName | string | "cf-turnstile-response" | Name of the input element. |
size | string | "normal" | The widget size. Can take the following values: "normal", "compact", "flexible", or "invisible". Normal: 300x65px, compact: 150x140px, flexible: 100% width (min: 300px) x 65px. "invisible" will show no widget and is only to be used with invisible type widgets. |
retry | string | "auto" | 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 upon failure. |
retryInterval | number | 8000 | When retry is set to "auto", retryInterval controls the time between retry attempts in milliseconds. The value must be a positive integer less than 900000. When retry is set to "never", this parameter has no effect. |
refreshExpired | string | "auto" | Automatically refreshes the token when it expires. Can take "auto", "manual" or "never". Read the Cloudflare docs for more info about handling expired widgets. |
refreshTimeout | string | "auto" | The refresh mode to use when the widget times out. The default is "auto". "never" will never refresh the widget, "manual" will prompt the user with a refresh button. |
execution | string | "render" | Execution controls when to obtain the token of the widget and can be on render or on execute. Read the Cloudflare docs for more info. |
appearance | string | "always" | Appearance controls when the widget is visible. It can be "always", "execute", or "interaction-only". Read the Cloudflare docs for more info. |
Read the Cloudflare docs to get more info about this options.
scriptOptions prop
| Option | Type | Default | Description |
|---|---|---|---|
id | string | "cf-turnstile-script" | Custom ID of the injected script. |
nonce | string | undefined | Custom nonce for the injected script. This option has no effect if injectScript is set to false. |
defer | boolean | true | Define if set the injected script as defer. This option has no effect if injectScript is set to false. |
async | boolean | true | Define if set the injected script as async. This option has no effect if injectScript is set to false. |
appendTo | string | "head" | Define if inject the script in the head or in the body. This option has no effect if injectScript is set to false. |
onLoadCallbackName | string | "onloadTurnstileCallback" | Custom name of the onload callback. This option has no effect if injectScript is set to false. |
onError | function | undefined | Callback invoked when script fails to load (e.g. Cloudflare has an outage). |
crossOrigin | string | undefined | Custom crossOrigin for the injected script. |