Client-side Render

Initializing and customizing the Turnstile widget on your webpage can be done via implicit or explicit rendering.

​​ Implicitly render the Turnstile widget

The HTML is scanned for elements that have a cf-turnstile class name:

<div class="cf-turnstile" data-sitekey="yourSitekey" data-callback="javascriptCallback"></div>

Once a challenge has been solved, a token is passed to the success callback. This token must be validated against our siteverify endpoint. A token can only be validated once and cannot be redeemed twice.

To configure the challenge, see Configurations containing data attributes and render parameters.

See the demo Open external link and its source code Open external link .

​​ Protect Forms

Turnstile is often used to protect forms on websites such as login forms, contact forms, and more. After inserting the JavaScript script tag, customers can embed <div class="cf-turnstile"></div> into their site to protect their forms.

For example:

<form action="/login" method="POST">
   <input type="text" placeholder="username"/>
   <input type="password" placeholder="password"/>
   <div class="cf-turnstile" data-sitekey="yourSitekey"></div> 
   <button type="submit" value="Submit">Log in</button>
</form>

An invisible input with the name cf-turnstile-response is added and will be sent to the server with the other fields.

​​ Disable implicit rendering

Implicit rendering can be disabled by customers by replacing the script from

https://challenges.cloudflare.com/turnstile/v0/api.js

to

https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit

When this option is used, HTML elements with the cf-turnstile class will not show a challenge. The turnstile.render function must be invoked using the following steps.

​​ Explicitly render the Turnstile widget

1. Insert the JavaScript tag:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

2. Once the script is embedded, you will have access to a global function with multiple callback options you can customize. To allow this function to work properly, an HTML element with the ID “example-container” must exist.
   The challenge can be invoked explicitly with the following JavaScript snippet:

window.onloadChlApiCallback = function () {
   const turnstileOptions = {
            sitekey: 'yourSiteKey',
            mode: managed’,
            callback: function(token) {
               console.log(`Challenge Success ${token}`);
            }
   };
   turnstile.render('#example-container', turnstileOptions); 
}

Turnstile can be programmatically loaded by invoking the turnstile.render() function in the global window object.

The turnstile.render: function (container: string | HTMLElement, params: RenderParameters) render takes an argument to a HTML widget.

If the invocation is successful, the function returns a widgetId. If the invocation is unsuccessful, the function returns undefined.

See the demo Open external link and its source code Open external link .

​​ Access a widget’s state

In addition to the render() function, Turnstile supports obtaining the widget’s response from a widgetId via the turnstile.getResponse(widgetId: string) function.

​​ Reset a widget

If a given widget has expired or needs to be reloaded, the turnstile.reset(widgetId: string) function can be used.

​​ Configurations