react-turnstile v1.1.3

react-turnstile

A very simple React library for Cloudflare Turnstile.

Installation

npm i react-turnstile

Usage

import Turnstile, { useTurnstile } from "react-turnstile";

// ...

function TurnstileWidget() {
  const turnstile = useTurnstile();
  return (
    <Turnstile
      sitekey="1x00000000000000000000AA"
      onVerify={(token) => {
        fetch("/login", {
          method: "POST",
          body: JSON.stringify({ token }),
        }).then((response) => {
          if (!response.ok) turnstile.reset();
        });
      }}
    />
  );
}

Turnstile tokens expire after 5 minutes, to automatically reset the challenge once they expire, set the autoResetOnExpire prop to true or reset the widget yourself using the onExpire callback.

Reducing Layout Shift

The turnstile iframe initially loads as invisible before becoming visible and expanding to the expected widget size.

This causes Layout Shift and reduces your Cumulative Layout Shift score and UX.

This can be fixed with the fixedSize={true} option, which will force the wrapper div to be the specific size of turnstile.

Bound Turnstile Object

The Bound Turnstile Object is given as argument to all callbacks and allows you to call certain window.turnstile functions without having to store the widgetId yourself.

function Component() {
  return (
    <Turnstile
      executution="execute"
      onLoad={(widgetId, bound) => {
        // before:
        window.turnstile.execute(widgetId);
        // now:
        bound.execute();
      }}
    />
  );
}

Documentation

Turnstile takes the following arguments:

And the following callbacks:

The callbacks also take an additional BoundTurnstileObject which exposes certain functions of window.turnstile which are already bound to the current widget, so you don't need track the widgetId yourself.

For more details on what each argument does, see the Cloudflare Documentation.