Props#
These are the props you can pass to the Turnstile component.
| Prop | Type | Description | Required |
|---|---|---|---|
siteKey | string | Your sitekey key, get one from here. | ✅ |
options | object | Widget render options. More info about this options 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 about this options below. | |
onWidgetLoad | function | Callback invoked when the widget is loaded or reloaded (e.g. after a 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. | |
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 injected and loaded. |
You can pass any valid HTML prop such as className, id, or style, based on the as prop.
options prop#
| 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', or 'invisible'. The normal size is 300x65px, the compact size is 130x120px. Use invisible if your key type is invisible, this option will prevent creating placeholder for the widget. |
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. |
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. |