react-turnstile

By default, the Turnstile widget's callbacks (like onSuccess) always access the latest state or props from your component without requiring the widget itself to re-render. This is achieved by the widget internally referencing the latest version of the function passed to it.

However, if your logic requires the widget to physically re-render (for example, to reset the widget or trigger a new challenge) whenever a callback function changes, you must explicitly enable this behavior using the rerenderOnCallbackChange prop.

// Default behavior: widget does NOT re-render when onSuccess changes,
// but the function itself will see the latest state.
<Turnstile siteKey="{{ siteKey }}" onSuccess={handleSuccess} />

// Re-render behavior: widget WILL re-render when onSuccess changes.
<Turnstile 
  siteKey="{{ siteKey }}" 
  rerenderOnCallbackChange={true} 
  onSuccess={currentCallback} 
/>

Turnstile tokens are single-use; once validated on the server, they are consumed. To prevent user friction when form validation fails (e.g., incorrect password), you can implement a client-side retry mechanism. This allows a user to attempt multiple form submissions using the same validated token before requiring a new Turnstile challenge.

Implementation Strategy

1. Track Tries: Use a state variable (e.g., triesLeft) to track how many submissions are allowed with the current token.
2. Conditional Validation: On form submission, only call your server-side /api/verify endpoint if triesLeft is 0. If triesLeft > 0, decrement the counter and proceed directly to the form action.
3. Resetting the Widget: If the Turnstile token itself fails validation or expires, use the turnstileRef.current?.reset() method to force a new challenge.
4. Handling Expiration: Use the onExpire callback to reset your local triesLeft counter to 0, ensuring the next submission triggers a fresh token validation.

Note: The retry counter is a client-side UX optimization only. You must always perform actual token validation on the server.

"use client";
import { useRef, useState } from "react";
import { Turnstile } from "@marsidev/react-turnstile";
import type { TurnstileInstance } from "@marsidev/react-turnstile";

const MAX_TRIES = 5;

export default function LoginForm() {
  const turnstileRef = useRef<TurnstileInstance | null>(null);
  const [triesLeft, setTriesLeft] = useState(0);
  const [captchaToken, setCaptchaToken] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);

    try {
      if (triesLeft === 0) {
        // 1. Validate the token on the server
        const res = await fetch("/api/verify", {
          method: "POST",
          body: JSON.stringify({ token: captchaToken }),
          headers: { "content-type": "application/json" },
        });

        const data = await res.json();

        if (!data.success) {
          setError("Captcha validation failed. Please try again.");
          turnstileRef.current?.reset(); // Reset widget on validation failure
          return;
        }

        // 2. Set remaining tries after successful token validation
        setTriesLeft(MAX_TRIES - 1);
        setError(null);
      } else {
        // 3. Use existing token and decrement tries
        setTriesLeft((prev) => prev - 1);
      }

      // 4. Proceed with the actual form submission
      const res = await fetch("/api/login", {
        method: "POST",
        body: JSON.stringify({
          username: formData.get("username"),
          password: formData.get("password"),
        }),
        headers: { "content-type": "application/json" },
      });

      const data = (await res.json()) as { success: boolean; message?: string };

      if (!data.success) {
        setError(data.message ?? "Login failed. Please try again.");
      }
    } catch {
      setError("An unexpected error occurred. Please try again.");
      turnstileRef.current?.reset();
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="text" name="username" placeholder="Username" />
      <input type="password" name="password" placeholder="Password" />
      {error && <p>{error}</p>}
      <Turnstile
        ref={turnstileRef}
        siteKey="{{ siteKey }}"
        onSuccess={(token) => setCaptchaToken(token)}
        onExpire={() => {
          setCaptchaToken(null);
          setTriesLeft(0);
        }}
      />
      <button type="submit">Login</button>
    </form>
  );
}

Token validation must be performed on your server to ensure security. The process involves two steps:

1. Client-side: Extract the token from the form submission. The token is available in the FormData under the key cf-turnstile-response.
2. Server-side: Send the token to the Cloudflare verification endpoint (https://challenges.cloudflare.com/turnstile/v0/siteverify) using a POST request. The body must be application/x-www-form-urlencoded containing your secret and the response (the token).

Use the TurnstileServerValidationResponse type to type the response from Cloudflare.

// 1. Client-side: Extract token from form
async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  const formData = new FormData(formRef.current!);
  const token = formData.get("cf-turnstile-response");

  const res = await fetch("/api/verify", {
    method: "POST",
    body: JSON.stringify({ token }),
    headers: {
      "content-type": "application/json",
    },
  });
  // ... handle response
}

// 2. Server-side: Verify with Cloudflare
export async function POST(request: Request) {
  const { token } = (await request.json()) as { token: string };

  const res = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", {
    method: "POST",
    body: `secret=${encodeURIComponent(secret)}&response=${encodeURIComponent(token)}`,
    headers: {
      "content-type": "application/x-www-form-urlencoded",
    },
  });

  const data = (await res.json()) as TurnstileServerValidationResponse;
  return new Response(JSON.stringify(data), {
    status: data.success ? 200 : 400,
    headers: { "content-type": "application/json" },
  });
}