Skip to main content

​
Interface

interface TurnstileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onError'> {
  siteKey: string
  onWidgetLoad?: (widgetID: string) => void
  onSuccess?: (token: string) => void
  onExpire?: (token: string) => void
  onError?: (error: string) => void
  onBeforeInteractive?: () => void
  onAfterInteractive?: () => void
  onUnsupported?: () => void
  onTimeout?: () => void
  options?: ComponentRenderOptions
  scriptOptions?: ScriptOptions
  as?: React.ElementType
  injectScript?: boolean
  onLoadScript?: () => void
  rerenderOnCallbackChange?: boolean
}

​
Required Props

​
siteKey
string
required
Your Cloudflare Turnstile sitekey. This sitekey is associated with the corresponding widget configuration and is created upon widget creation.Get your sitekey from the Cloudflare Dashboard.

​
Callback Props

​
onWidgetLoad
(widgetID: string) => void
Callback invoked after a successful render of the widget. The callback is passed the widget ID.Note: Does not trigger when the widget is reset.
​
onSuccess
(token: string) => void
Callback invoked upon successful completion of the challenge. The callback receives a token that can be validated on your server.See Server Validation for how to validate tokens.
​
onExpire
(token: string) => void
Callback invoked when a challenge expires. The callback receives the expired token.
​
onError
(error: string) => void
Callback invoked when there is an error (e.g., network error or challenge failure). The callback receives an error code.Refer to Client-side errors in the Cloudflare documentation.
​
onBeforeInteractive
() => void
Callback invoked before the user is prompted for interactivity.
​
onAfterInteractive
() => void
Callback invoked when the interactive challenge has been solved.
​
onUnsupported
() => void
Callback invoked when the browser is not supported by Turnstile.
​
onTimeout
() => void
Callback invoked when the Turnstile widget times out.

​
Configuration Props

​
options
ComponentRenderOptions
Custom widget render options that control the appearance and behavior of the Turnstile widget.See ComponentRenderOptions for all available options.
​
scriptOptions
ScriptOptions
Custom options for the injected Turnstile script, including nonce, defer, async, and more.See ScriptOptions for all available options.
​
as
React.ElementType
default:"'div'"
Define the HTML tag of the widget container. Defaults to 'div'.
<Turnstile as="section" siteKey="..." />
​
injectScript
boolean
default:"true"
Controls whether the Turnstile script is automatically injected. Set to false if you want to inject the script manually.
<Turnstile injectScript={false} siteKey="..." />
​
onLoadScript
() => void
Callback invoked when the Turnstile script is loaded.
​
rerenderOnCallbackChange
boolean
default:"false"
Controls whether the widget re-renders when callback props change.
  • false (default): Stable callbacks - better performance, callbacks don’t cause widget re-renders
  • true: Dynamic callbacks - widget re-renders when callbacks change, useful for intentional callback updates
Important: When set to true, wrap your callback functions with useCallback to prevent unnecessary widget re-renders on every parent component re-render.
const handleSuccess = useCallback((token) => {
  console.log('Success:', token)
}, [])

<Turnstile
  rerenderOnCallbackChange={true}
  onSuccess={handleSuccess}
  siteKey="..."
/>

​
HTML Attributes

Since TurnstileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onError'>, you can pass any standard HTML div attributes: 
<Turnstile
  siteKey="your-site-key"
  className="my-turnstile"
  style={{ margin: '20px' }}
  data-testid="turnstile-widget"
/>

Build docs developers (and LLMs) love

Get started for freeTalk to us