Embed the widget

Last updated Jun 17, 2026 Learn how to add the Turnstile widget to your webpage using implicit or explicit rendering methods.

Turnstile offers two ways to add widgets to your page. Implicit rendering automatically scans your HTML for widget containers when the page loads. Explicit rendering gives you programmatic control to create widgets at any time using JavaScript. Use implicit rendering for static pages where forms exist at page load. Use explicit rendering for dynamic content and single-page applications (SPAs) where forms are created after the initial page load.

Prerequisites

Before you begin, you must have:

• A Cloudflare account
• A Turnstile widget with a sitekey
• Access to edit your website's HTML
• Basic knowledge of HTML and JavaScript

Process

1. Page load: The Turnstile script loads and scans for elements or waits for programmatic calls.
2. Widget rendering: Widgets are created and begin running challenges.
3. Token generation: When a challenge is completed, a token is generated.
4. Form integration: The token is made available via callbacks or hidden form fields.
5. Server validation: Your server receives the token and validates it using the Siteverify API.

Implicit rendering

Implicit rendering automatically scans your HTML for elements with the cf-turnstile class and renders widgets without additional JavaScript code. This set up is ideal for static pages where you want the widget to load immediately when the page loads.

Use cases

Cloudflare recommends using implicit rendering on the following scenarios:

• You have simple implementations and want a quick integration.
• You have static websites with straightforward forms.
• You want widgets to appear immediately on pageload.
• You do not need programmatic control of the widget.

Implementation

1. Add the Turnstile script

Include the Turnstile Script: Add the Turnstile JavaScript API to your HTML file within the <head> section or just before the closing </body> tag.

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

Caution

The api.js file must be fetched from the exact URL shown above. Proxying or caching this file will cause Turnstile to fail when future updates are released.

2. (Optional) Optimize performance with resource hints

Add resource hints to improve loading performance by establishing early connections to Cloudflare servers. Place this <link> tag in your HTML <head> section before the Turnstile script.

<link rel="preconnect" href="https://challenges.cloudflare.com" />

3. Add widget elements

Add widget containers where you want the challenges to appear on your website.

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

4. Configure with data attributes

Customize your widgets using data attributes. Insert a div element where you want the widget to appear.

<div
    class="cf-turnstile"
    data-sitekey="<YOUR-SITE-KEY>"
    data-theme="light"
    data-size="normal"
    data-callback="onSuccess"
></div>

Once a challenge has been solved, a token is passed to the success callback. This token must be validated against our Siteverify endpoint.

Complete implicit rendering examples by use case

<details>

<summary>

Basic login form

</summary>

Turnstile is often used to protect forms on websites such as login forms or contact forms. You can embed the widget within your <code><form></code> tag.

Examplehtml

<!DOCTYPE html>
<html>
<head>
    <title>Login Form</title>
    <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
    <form action="/login" method="POST">
        <input type="text" name="username" placeholder="Username" autocomplete="username" required />
        <input type="password" name="password" placeholder="Password" autocomplete="current-password" required />

<!-- Turnstile widget with basic configuration -->
        <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
        <button type="submit">Log in</button>
    </form>

</body>
</html>

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

Complete HTML examplehtml

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Implicit Rendering with Cloudflare Turnstile</title>
        <script
            src="https://challenges.cloudflare.com/turnstile/v0/api.js"
            async
            defer
        ></script>
    </head>
    <body>
        <h1>Contact Us</h1>
        <form action="/submit" method="POST">
            <label for="name">Name:</label><br />
            <input type="text" id="name" name="name" required /><br />
            <label for="email">Email:</label><br />
            <input type="email" id="email" name="email" required /><br />
            <!-- Turnstile Widget -->
            <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
            <br />
            <button type="submit">Submit</button>
        </form>
    </body>
</html>

</details>

<details>

<summary>

Advanced form with callbacks

</summary>

Examplehtml

<form action="/contact" method="POST" id="contact-form">
    <input type="email" name="email" placeholder="Email" required />
    <textarea name="message" placeholder="Message" required></textarea>
    <!-- Widget with callbacks and custom configuration -->
    <div
        class="cf-turnstile"
        data-sitekey="<YOUR-SITE-KEY>"
        data-theme="auto"
        data-size="flexible"
        data-callback="onTurnstileSuccess"
        data-error-callback="onTurnstileError"
        data-expired-callback="onTurnstileExpired"
    ></div>
    <button type="submit" id="submit-btn" disabled>Send Message</button>
</form>

<script>
    function onTurnstileSuccess(token) {
        console.log("Turnstile success:", token);
        document.getElementById("submit-btn").disabled = false;
    }
    function onTurnstileError(errorCode) {
        console.error("Turnstile error:", errorCode);
        document.getElementById("submit-btn").disabled = true;
    }
    function onTurnstileExpired() {
        console.warn("Turnstile token expired");
        document.getElementById("submit-btn").disabled = true;
    }
</script>

</details>

<details>

<summary>

Multiple widgets with different configurations

</summary>

Examplehtml

<!-- Compact widget for newsletter signup -->
<form action="/newsletter" method="POST">
    <input type="email" name="email" placeholder="Email" />
    <div
        class="cf-turnstile"
        data-sitekey="<YOUR-SITE-KEY>"
        data-size="compact"
        data-action="newsletter"
    ></div>
    <button type="submit">Subscribe</button>
</form>

<!-- Normal widget for contact form -->
<form action="/contact" method="POST">
    <input type="text" name="name" placeholder="Name" />
    <input type="email" name="email" placeholder="Email" />
    <textarea name="message" placeholder="Message"></textarea>
    <div
        class="cf-turnstile"
        data-sitekey="<YOUR-SITE-KEY>"
        data-action="contact"
        data-theme="dark"
    ></div>
    <button type="submit">Send</button>
</form>

</details>

<details>

<summary>

Automatic form integration

</summary>

When you embed a Turnstile widget inside a <code><form></code> element, an invisible input field with the name <code>cf-turnstile-response</code> is automatically created. This field contains the verification token and gets submitted with your other form data.

<form action="/submit" method="POST">
    <input type="text" name="data" />
    <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>
    <!-- Hidden field automatically added: -->
    <!-- <input type="hidden" name="cf-turnstile-response" value="TOKEN_VALUE" /> -->
    <button type="submit">Submit</button>
</form>

</details>

Explicit rendering

Explicit rendering gives you programmatic control over when and where the widget appears and how the widgets are created using JavaScript functions. This method is suitable for dynamic content, single-page applications (SPAs), or conditional rendering based on user interactions.

Use cases

Cloudflare recommends using explicit rendering on the following scenarios:

• You have dynamic websites and single-page applications (SPAs).
• You need to control the timing of widget creation.
• You want to conditionally render the widget based on visitor interactions.
• You want multiple widgets with different configurations.
• You have complex applications requiring widget lifecycle management.

Implementation

1. Add the script to your website with explicit rendering

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

2. Create container elements

Create containers without the cf-turnstile class.

<div id="turnstile-container"></div>

3. Render the widgets programmatically

Call turnstile.render() when you are ready to create the widget.

const widgetId = turnstile.render("#turnstile-container", {
    sitekey: "<YOUR-SITE-KEY>",
    callback: function (token) {
        console.log("Success:", token);
    },
});