React Turnstile

Cloudflare Turnstile integration for React.

Features

• 🕵️‍♀️ Privacy-first - No user tracking, no cookies, GDPR-friendly by design
• 📦 Lightweight - Only 6.3 KB minified
• 💪 Smart verification - Often invisible to users with minimal interaction
• 💉 Zero config - Automatic script injection, works out of the box
• 📐 Multiple widget sizes - normal, compact, flexible, invisible
• 🎮 Imperative API - Control via ref: reset(), execute(), getResponse(), isExpired()
• ⚡️ SSR ready - Works with Next.js, Remix, and any React SSR framework
• 💻 Full TypeScript support

📖 Read the docs →    🚀 See the demo →

Getting started

1. Follow these steps to obtain a free site key and secret key from Cloudflare.
2. Install @marsidev/react-turnstile into your React project.

pnpm add @marsidev/react-turnstile

Usage

Basic

import { Turnstile } from '@marsidev/react-turnstile'

function Widget() {
  return <Turnstile siteKey='1x00000000000000000000AA' />
}

With form and imperative API

import { Turnstile } from '@marsidev/react-turnstile'
import type { TurnstileInstance } from '@marsidev/react-turnstile'
import { useRef } from 'react'

function LoginForm() {
  const turnstileRef = useRef<TurnstileInstance | null>(null)

  async function handleSubmit(e: FormEvent) {
    e.preventDefault()
    const token = turnstileRef.current?.getResponse()
    // Send token to your server...
    turnstileRef.current?.reset() // Reset after submission
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />
      <Turnstile
        ref={turnstileRef}
        siteKey='1x00000000000000000000AA'
      />
      <button type="submit">Login</button>
    </form>
  )
}

Contributing

Any contributions are greatly appreciated. If you have a suggestion that would make this project better, please fork the repo and create a Pull Request. You can also open an issue.

Development

• Fork or clone this repository.
• Install dependencies with pnpm install.
• Run pnpm dev to start both the library (with HMR) and the Next.js demo app concurrently

For reference, the project structure is as follows:

.
├── packages/lib/    # Library source code
├── demos/nextjs/    # Next.js demo app
└── docs/            # Documentation

Support

If you find this library useful, you can buy me a coffee:

Contributors

License

Published under the MIT License.