@marsidev/react-turnstile v0.6.1

Features

• 💪 smart verification with minimal user interaction
• 🕵️‍♀️ privacy-focused approach
• 💉 automatic script injection
• ⚡️ ssr ready

Demo

https://react-turnstile.vercel.app/

Install

1. Follow these steps to obtain a free site key and secret key from Cloudflare.

2. Install @marsidev/react-turnstile into your React project.

   npm i @marsidev/react-turnstile

   Or using any custom package manager:

   pnpm add @marsidev/react-turnstile

   yarn add @marsidev/react-turnstile

   bun add @marsidev/react-turnstile

   ni @marsidev/react-turnstile

Usage

The only required prop is the siteKey.

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

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

Props

Render options

All this options are optional.

Read the docs to get more info about this options.

The widget is wrapped in a div, so you can pass any valid div prop such as className, id, or style.

Script options

Examples

Rendering the widget:

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

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

Rendering the widget with custom props:

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

function Widget() {
  return (
    <Turnstile
      siteKey='1x00000000000000000000AA'
      className='fixed bottom-4 right-4'
      options={{
        action: 'submit-form',
        theme: 'light',
        size: 'compact'
      }}
      scriptOptions={{
        appendTo: 'body'
      }}
    />
  )
}

Managing widget rendering status:

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

function Widget() {
  const [status, setStatus] = useState()

  return (
    <Turnstile
      siteKey='1x00000000000000000000AA'
      onError={() => setStatus('error')}
      onExpire={() => setStatus('expired')}
      onSuccess={() => setStatus('solved')}
    />
  )
}

onExpire does not take effect unless you set autoResetOnExpire to false.

Getting the token after solving the challenge:

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

function Widget() {
  const [token, setToken] = useState()

  return (
    <Turnstile
      siteKey='1x00000000000000000000AA'
      onSuccess={(token) => setToken(token)}
    />
  )
}

Interacting with the widget:

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

function Widget() {
  const ref = useRef(null)

  return (
    <>
      <Turnstile ref={ref} siteKey='1x00000000000000000000AA'/>

      <button onClick={() => alert(ref.current?.getResponse())}>
        Get response
      </button>

      <button onClick={() => ref.current?.reset()}>
        Reset widget
      </button>

      <button onClick={() => ref.current?.remove()}>
        Remove widget
      </button>

      <button onClick={() => ref.current?.render()}>
        Render widget
      </button>
    </>
  )
}

Interacting with the widget (using TypeScript):

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

function Widget() {
  const ref = useRef<TurnstileInstance>(null)

  return (
    <>
      <Turnstile ref={ref} siteKey='1x00000000000000000000AA'/>

      <button onClick={() => alert(ref.current?.getResponse())}>
        Get response
      </button>
    </>
  )
}

Validating a token:

// LoginForm.jsx
import { useRef } from 'react'
import { Turnstile } from '@marsidev/react-turnstile'

export default function LoginForm() {
  const formRef = useRef(null)

  async function handleSubmit(event) {
    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'
      }
    })

    const data = await res.json()
    if (data.success) {
      // the token has been validated
    }
  }

  return (
    <form ref={formRef} onSubmit={handleSubmit}>
      <input type="text" placeholder="username"/>
      <input type="password" placeholder="password"/>
      <Turnstile siteKey='1x00000000000000000000AA'/>
      <button type='submit'>Login</button>
    </form>
  )
}

// `pages/api/verify.js`
// this is an example of a next.js api route
// this code runs on the server
const endpoint = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'
const secret = '1x0000000000000000000000000000000AA'

export default async function handler(request, response) {
  const body = `secret=${encodeURIComponent(secret)}&response=${encodeURIComponent(request.body.token)}`

  const res = await fetch(endpoint, {
    method: 'POST',
    body,
    headers: {
      'content-type': 'application/x-www-form-urlencoded'
    }
  })

  const data = await res.json()
  return response.json(data)
}

Check the demo and his source code to see a code similar to the above in action.

Check the docs for more info about server side validation.

As you might noted, there is three ways to get the token response from a solved challenge:

• by catching it from the onSuccess callback.
• by calling the .getResponse() method.
• by reading the widget response input with name cf-turnstile-response. This one is not an option if you set options.fieldResponse to false.

Handling widget expiring:

By default, you don't need to handle the widget expiring, unless you set autoResetOnExpire to false.

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

function Widget() {
  const ref = useRef(null)

  return (
    <Turnstile
      ref={ref}
      autoResetOnExpire={false}
      siteKey='1x00000000000000000000AA'
      onExpire={() => ref.current?.reset()}
    />
  )
}

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 pnpm.
• Install dependencies with pnpm install.
• You can use pnpm dev to start the demo page in development mode, which also rebuild the library when file changes are detected in the src folder.
• You also can use pnpm stub, which run unbuild --stub, a passive watcher to use the library while developing without needing to watch and rebuild. However, this option can't be used in an esm context.

Credits

Inspired by

• nuxt-turnstile
• svelte-turnstile
• react-google-recaptcha-v3
• reaptcha

License

Published under the MIT License.