Skip to main content

​
Interface

interface ComponentRenderOptions extends Pick<
  Turnstile.RenderParameters,
  'action' | 'cData' | 'theme' | 'retry' | 'language' | 'execution' | 'appearance'
> {
  tabIndex?: number
  responseField?: boolean
  responseFieldName?: string
  retryInterval?: number
  size?: WidgetSize
  refreshExpired?: RefreshExpiredMode
  refreshTimeout?: RefreshTimeoutMode
  feedbackEnabled?: boolean
}

​
Usage

Pass these options via the options prop: 
<Turnstile
  siteKey="your-site-key"
  options={{
    theme: 'dark',
    size: 'compact',
    language: 'en'
  }}
/>

​
Appearance Options

​
theme
'auto' | 'light' | 'dark'
default:"'auto'"
The theme of the Turnstile widget.
  • 'auto': Respects the user’s system preference
  • 'light': Forces light theme
  • 'dark': Forces dark theme
options={{ theme: 'dark' }}
​
size
WidgetSize
default:"'normal'"
The size of the Turnstile widget.Accepted values:
  • 'normal': 300x65px
  • 'compact': 150x140px
  • 'flexible': 100% width (min: 300px) x 65px
  • 'invisible': No visible widget (for invisible type widgets only)
options={{ size: 'compact' }}
​
appearance
AppearanceMode
default:"'always'"
Controls when the widget is visible.
  • 'always': Widget is always visible
  • 'execute': Widget only appears when executing
  • 'interaction-only': Widget only shown when/if interactivity is required
options={{ appearance: 'interaction-only' }}
​
language
string
default:"'auto'"
The language for the widget. Must be a valid ISO 639-1 country code or 'auto'.Examples: 'en', 'es', 'fr', 'de', 'ja', 'zh-CN'See TurnstileLangCode for supported languages.
options={{ language: 'es' }}

​
Behavior Options

​
execution
ExecutionMode
default:"'render'"
Controls when to obtain the token.
  • 'render': Obtains token immediately upon render (default)
  • 'execute': Obtains token only when .execute() method is called
options={{ execution: 'execute' }}
​
retry
FailureRetryMode
default:"'auto'"
How to retry on widget failure.
  • 'auto': Automatically allows the user to retry
  • 'never': Never allows retry
options={{ retry: 'auto' }}
​
retryInterval
number
default:"8000"
Duration in milliseconds before the widget automatically retries after a failure.
options={{ retryInterval: 5000 }} // 5 seconds
​
refreshExpired
RefreshExpiredMode
default:"'auto'"
The refresh mode when a token expires.
  • 'auto': Automatically refreshes the widget
  • 'manual': Prompts the user with a refresh button
  • 'never': Never refreshes the widget
options={{ refreshExpired: 'manual' }}
​
refreshTimeout
RefreshTimeoutMode
default:"'auto'"
The refresh mode when the widget times out.
  • 'auto': Automatically refreshes the widget
  • 'manual': Prompts the user with a refresh button
  • 'never': Never refreshes the widget
options={{ refreshTimeout: 'manual' }}

​
Data Options

​
action
string
A customer value used to differentiate widgets under the same sitekey in analytics. Returned upon validation.Useful for tracking which form or page the widget was used on.
options={{ action: 'login' }}
​
cData
string
Customer payload that can be used to attach customer data to the challenge. Returned upon validation.The data integrity is protected from modifications by attackers.
options={{ cData: JSON.stringify({ userId: '12345' }) }}

​
Form Integration Options

​
responseField
boolean
default:"true"
Whether to add a hidden response input element with the Turnstile token.When true, the token is automatically added as a hidden input in the container.
options={{ responseField: true }}
​
responseFieldName
string
default:"'cf-turnstile-response'"
The name of the hidden input element added to the container.
options={{ responseFieldName: 'turnstile_token' }}

​
Accessibility Options

​
tabIndex
number
default:"0"
The tabindex of Turnstile’s iframe for accessibility purposes.
options={{ tabIndex: 1 }}
​
feedbackEnabled
boolean
default:"true"
Allows Cloudflare to gather visitor feedback upon widget failure.
options={{ feedbackEnabled: false }}

​
Complete Example

<Turnstile
  siteKey="your-site-key"
  options={{
    theme: 'dark',
    size: 'compact',
    language: 'en',
    execution: 'render',
    appearance: 'always',
    retry: 'auto',
    retryInterval: 8000,
    refreshExpired: 'auto',
    refreshTimeout: 'auto',
    responseField: true,
    responseFieldName: 'cf-turnstile-response',
    tabIndex: 0,
    feedbackEnabled: true,
    action: 'login',
    cData: JSON.stringify({ page: 'login' })
  }}
/>

​
Type Definitions

type WidgetSize = 'normal' | 'compact' | 'flexible' | 'invisible'

type AppearanceMode = 'always' | 'execute' | 'interaction-only'

type ExecutionMode = 'render' | 'execute'

type FailureRetryMode = 'never' | 'auto'

type RefreshExpiredMode = 'never' | 'manual' | 'auto'

type RefreshTimeoutMode = 'never' | 'manual' | 'auto'

Build docs developers (and LLMs) love

Get started for freeTalk to us