FM / basic-setup

/opt/canhelp/node_modules/@marsidev/react-turnstile/skills/basic-setup/

/opt/canhelp/node_modules/@marsidev/react-turnstile/skills/basic-setup

Name	Size	Mode	Actions
SKILL.md	5294	0644	edit dl rm

Edit: /opt/canhelp/node_modules/@marsidev/react-turnstile/skills/basic-setup/SKILL.md (5294B)

# Basic Setup

Install and render a Cloudflare Turnstile widget in your React application.

## Installation

```bash
# npm
npm install @marsidev/react-turnstile

# pnpm
pnpm add @marsidev/react-turnstile

# yarn
yarn add @marsidev/react-turnstile

# bun
bun add @marsidev/react-turnstile
```

## Get Your Site Key

Before using Turnstile, you need a site key from Cloudflare:

1. Go to the [Cloudflare Turnstile dashboard](https://developers.cloudflare.com/turnstile/get-started/)
2. Create a new widget
3. Copy your site key (starts with `0x` or `1x` for testing)

**Note:** Site keys are **NOT** secret. They are safe to include in client-side code.

## Basic Usage

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

export default function LoginForm() {
  return (
    <form>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />

{/* Basic Turnstile widget */}
      <Turnstile siteKey="YOUR_SITE_KEY" />

<button type="submit">Login</button>
    </form>
  )
}
```

## Widget Sizes

Choose the size that fits your layout:

| Size | Dimensions | Best For |
|------|------------|----------|
| `normal` (default) | 300×65px | Most forms, standard layouts |
| `compact` | 150×140px | Mobile, tight spaces |
| `flexible` | 100% width × 65px | Responsive layouts |
| `invisible` | 0×0px | Hidden widgets (requires Invisible widget type from Cloudflare) |

```tsx
// Compact size for mobile
<Turnstile
  siteKey="YOUR_SITE_KEY"
  options={{ size: 'compact' }}
/>

// Flexible width
<Turnstile
  siteKey="YOUR_SITE_KEY"
  options={{ size: 'flexible' }}
/>
```

## Handling the Success Token

Use the `onSuccess` callback to receive the verification token:

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

export default function LoginForm() {
  const [token, setToken] = useState<string | null>(null)

return (
    <form>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />

<Turnstile
        siteKey="YOUR_SITE_KEY"
        onSuccess={(token) => setToken(token)}
      />

<button type="submit" disabled={!token}>
        Login
      </button>
    </form>
  )
}
```

## Complete Form Example

```tsx
'use client' // For Next.js App Router
import { Turnstile } from '@marsidev/react-turnstile'
import { useState } from 'react'

export default function ContactForm() {
  const [token, setToken] = useState<string | null>(null)
  const [isSubmitting, setIsSubmitting] = useState(false)

async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    if (!token) return

setIsSubmitting(true)

// Send token to your server for validation
    const response = await fetch('/api/contact', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token, /* other form data */ })
    })

if (response.ok) {
      // Handle success
    }

setIsSubmitting(false)
  }

return (
    <form onSubmit={handleSubmit}>
      <input type="text" name="name" placeholder="Name" required />
      <input type="email" name="email" placeholder="Email" required />
      <textarea name="message" placeholder="Message" required />

<button type="submit" disabled={!token || isSubmitting}>
        {isSubmitting ? 'Sending...' : 'Send Message'}
      </button>
    </form>
  )
}
```

## Common Mistakes

### ❌ Using Invisible Size Without Invisible Widget Type

The `invisible` size is **only** for the Invisible widget type from Cloudflare. Using it with a normal widget shows nothing.

**Wrong:**
```tsx
// Shows nothing if widget type is not "Invisible"
<Turnstile siteKey="xxx" options={{ size: 'invisible' }} />
```

**Correct:**
```tsx
// Use visible sizes for normal widgets
<Turnstile siteKey="xxx" options={{ size: 'normal' }} />
<Turnstile siteKey="xxx" options={{ size: 'compact' }} />
<Turnstile siteKey="xxx" options={{ size: 'flexible' }} />
```

## Next Steps

- **Customize appearance:** See [widget-customization skill](./widget-customization/SKILL.md)
- **Handle tokens properly:** See [token-lifecycle skill](./token-lifecycle/SKILL.md)
- **Next.js integration:** See [nextjs-ssr skill](./nextjs-ssr/SKILL.md)
- **Multiple widgets:** See [multiple-widgets skill](./multiple-widgets/SKILL.md)

## Testing During Development

Use Cloudflare's test keys that always pass validation:

- **Site key:** `1x00000000000000000000AA`
- **Secret key:** `1x0000000000000000000000000000000AA`

See: https://developers.cloudflare.com/turnstile/troubleshooting/testing/

--- name: basic-setup description: > Install and render your first Turnstile widget with required configuration. Activate this skill when starting a new project with react-turnstile or when implementing basic CAPTCHA protection for the first time. triggers: - 'install turnstile react' - 'add captcha to form' - 'setup cloudflare turnstile' - 'basic turnstile example' - 'how to use @marsidev/react-turnstile' - 'turnstile widget not showing' category: core metadata: library: '@marsidev/react-turnstile' library_version: '1.4.2' framework: React --- # Basic Setup Install and render a Cloudflare Turnstile widget in your React application. ## Installation ```bash # npm npm install @marsidev/react-turnstile # pnpm pnpm add @marsidev/react-turnstile # yarn yarn add @marsidev/react-turnstile # bun bun add @marsidev/react-turnstile ``` ## Get Your Site Key Before using Turnstile, you need a site key from Cloudflare: 1. Go to the [Cloudflare Turnstile dashboard](https://developers.cloudflare.com/turnstile/get-started/) 2. Create a new widget 3. Copy your site key (starts with `0x` or `1x` for testing) **Note:** Site keys are **NOT** secret. They are safe to include in client-side code. ## Basic Usage ```tsx import { Turnstile } from '@marsidev/react-turnstile' export default function LoginForm() { return (

{/* Basic Turnstile widget */} ) } ``` ## Widget Sizes Choose the size that fits your layout: | Size | Dimensions | Best For | |------|------------|----------| | `normal` (default) | 300×65px | Most forms, standard layouts | | `compact` | 150×140px | Mobile, tight spaces | | `flexible` | 100% width × 65px | Responsive layouts | | `invisible` | 0×0px | Hidden widgets (requires Invisible widget type from Cloudflare) | ```tsx // Compact size for mobile // Flexible width ``` ## Handling the Success Token Use the `onSuccess` callback to receive the verification token: ```tsx import { Turnstile } from '@marsidev/react-turnstile' import { useState } from 'react' export default function LoginForm() { const [token, setToken] = useState(null) return (

setToken(token)} /> ) } ``` ## Complete Form Example ```tsx 'use client' // For Next.js App Router import { Turnstile } from '@marsidev/react-turnstile' import { useState } from 'react' export default function ContactForm() { const [token, setToken] = useState(null) const [isSubmitting, setIsSubmitting] = useState(false) async function handleSubmit(e: React.FormEvent) { e.preventDefault() if (!token) return setIsSubmitting(true) // Send token to your server for validation const response = await fetch('/api/contact', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ token, /* other form data */ }) }) if (response.ok) { // Handle success } setIsSubmitting(false) } return (