react-native-turnstile-next

A React Native wrapper for Cloudflare Turnstile using react-native-webview.

How It Works

The cookies used by Cloudflare Turnstile are incompatible with react-native-webview. This package renders a bridge page directly inside a WebView, uses your configured domain as the page origin, and forwards Turnstile widget events back to your React Native app.

Important: Add the domain you pass to ReactNativeTurnstile to your Turnstile domains list.

Installation

npm i react-native-turnstile-next react-native-webview

If you're running Expo, then:

npx expo install react-native-webview
npm install react-native-turnstile-next

Usage

import ReactNativeTurnstile from "react-native-turnstile-next";

function TurnstileWidget() {
  return (
    <ReactNativeTurnstile
      sitekey="xxxxxxxxxxxxxxxxxxx"
      domain="captcha.example.com"
      onVerify={(token) => console.log(token)}
      onError={(error) => console.log(error)}
      style={{ alignSelf: "center" }}
    />
  );
}

Turnstile tokens expire after 5 minutes. Use refreshExpired="auto" to let the widget refresh expired tokens, or reset the widget yourself with the ref API.

Programmatic Reset

import { useRef } from "react";
import { Button } from "react-native";
import ReactNativeTurnstile from "react-native-turnstile-next";

import type { TurnstileRef } from "react-native-turnstile-next";

function TurnstileWidget() {
  const turnstileRef = useRef<TurnstileRef>(null);

  async function submitForm() {
    const result = await fetch("/path/to/some/api");

    if (!result.ok) {
      turnstileRef.current?.reset();
      throw new Error(`Request failed with code ${result.status}`);
    }
  }

  return (
    <>
      <ReactNativeTurnstile
        ref={turnstileRef}
        sitekey="xxxxxxxxxxxxxxxxxxx"
        domain="captcha.example.com"
        onVerify={(token) => console.log(token)}
        onExpire={() => turnstileRef.current?.reset()}
      />
      <Button title="Submit" onPress={submitForm} />
    </>
  );
}

Ref API

ReactNativeTurnstile exposes an imperative ref:

import { useRef } from "react";
import { Button } from "react-native";
import ReactNativeTurnstile from "react-native-turnstile-next";

import type { TurnstileRef } from "react-native-turnstile-next";

function TurnstileWidget() {
  const turnstileRef = useRef<TurnstileRef>(null);

  return (
    <>
      <ReactNativeTurnstile
        ref={turnstileRef}
        sitekey="xxxxxxxxxxxxxxxxxxx"
        domain="captcha.example.com"
        execution="execute"
        onVerify={(token) => console.log(token)}
      />
      <Button title="Execute" onPress={() => turnstileRef.current?.execute()} />
      <Button title="Reset" onPress={() => turnstileRef.current?.reset()} />
    </>
  );
}

reset() resets the current Turnstile widget without reloading the internal WebView. reload() reloads the internal WebView. execute() injects an execute request into the bridge page.

The older resetRef prop and resetTurnstile(resetRef) helper are still available for compatibility.

Error Handling

onError returns a structured TurnstileError object based on the Cloudflare Turnstile error codes:

<ReactNativeTurnstile
  sitekey="xxxxxxxxxxxxxxxxxxx"
  domain="captcha.example.com"
  onError={(error) => {
    console.log(error.errorCode);
    console.log(error.description);
    console.log(error.retry);
    console.log(error.troubleshooting);
    console.log(error.referenceUrl);
  }}
/>

Example:

{
  errorCode: 110200,
  description: "Domain not authorized",
  retry: false,
  troubleshooting: "Add current domain in Hostname Management.",
  raw: "110200",
  referenceUrl: "https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/"
}

Unknown errors return errorCode: "unknown" and include the same referenceUrl so users can inspect Cloudflare's latest documentation.

Custom Domain

Pass the hostname configured for your Turnstile sitekey as domain:

<ReactNativeTurnstile
  sitekey="xxxxxxxxxxxxxxxxxxx"
  domain="atplquestions.com"
/>

The package renders the Turnstile bridge HTML directly inside the WebView and uses the provided domain as the page origin. It does not navigate the WebView to your website. domain accepts both captcha.example.com and https://captcha.example.com.

WebView Props

Use webViewProps to pass supported props to the internal WebView:

<ReactNativeTurnstile
  sitekey="xxxxxxxxxxxxxxxxxxx"
  domain="captcha.example.com"
  webViewProps={{
    cacheEnabled: false,
    incognito: true,
    userAgent: "MyApp",
  }}
/>

source, onMessage, and ref are controlled by this package and cannot be overridden through webViewProps.

Documentation

ReactNativeTurnstile takes the following arguments:

| name | required | type | description | | ----------------- | -------- | ----------------------------------------- | ---------------------------------------------- | | sitekey | Yes | string | Sitekey of your Turnstile widget. | | domain | Yes | string | Turnstile hostname used as the internal WebView origin. | | action | No | string | Turnstile action value. | | cData | No | string | Custom data passed to Turnstile. | | theme | No | "light" \| "dark" \| "auto" | Widget theme. | | language | No | SupportedLanguages \| "auto" | Widget language. | | size | No | "compact" \| "normal" | Widget size. | | fixedSize | No | boolean | Whether the bridge should use fixed sizing. | | tabIndex | No | number | Widget tab index. | | responseField | No | boolean | Controls generation of the response input. | | responseFieldName | No | string | Changes the response input name. | | retry | No | "auto" \| "never" | Retry behavior. | | retryInterval | No | number | Retry interval in milliseconds. | | refreshExpired | No | "auto" \| "manual" \| "never" | Expired token refresh behavior. | | appearance | No | "always" \| "execute" \| "interaction-only" | Widget appearance behavior. | | execution | No | "render" \| "execute" | Widget execution behavior. | | id | No | string | ID of the widget container. | | resetRef | No | TurnstileResetRef | Legacy ref in which the package injects reset(). | | className | No | string | Provided to facilitate NativeWind classes. | | style | No | StyleProp<ViewStyle> | Passed to the React Native View container. | | webViewProps | No | TurnstileWebViewProps | Additional props passed to the internal WebView. source and onMessage are controlled by this package. |

And the following callbacks:

| name | required | arguments | description | | ------------------- | -------- | ----------------- | -------------------------------------------- | | onVerify | No | token | Called when the challenge is passed. | | onLoad | No | widgetId | Called when the widget is loaded. | | onError | No | TurnstileError | Called when an error occurs. | | onExpire | No | token | Called when the token expires. | | onTimeout | No | - | Called when the challenge times out. | | onAfterInteractive | No | - | Called after the widget becomes interactive. | | onBeforeInteractive | No | - | Called before the widget becomes interactive. | | onUnsupported | No | - | Called when the browser is unsupported. |

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

Type Exports

The package exports these public types:

import type {
  ReactNativeTurnstileEvent,
  TurnstileCallbacks,
  TurnstileError,
  TurnstileErrorCode,
  TurnstileEvent,
  TurnstileProps,
  TurnstileRef,
  TurnstileResetRef,
  TurnstileWebViewProps,
} from "react-native-turnstile-next";

Expo Example

An Expo example is available in examples/expo:

cd examples/expo
npm install
npm run ios

Credits

This package is a fork of react-native-turnstile by Jay Simons. It continues development under the react-native-turnstile-next package name with updated publishing metadata, TypeScript exports, custom bridge support, and additional React Native APIs.