godgpt-web-waitlist

A configurable React waitlist modal component with Mailchimp and Cloudflare Turnstile support.

Features

• 🎨 Configurable Content - Customize title, subtitle, and success messages
• 🔄 Controlled & Uncontrolled Modes - Use with or without external state management
• 📧 Mailchimp Compatible - Form fields match Mailchimp's expected schema
• 🛡️ Cloudflare Turnstile - Built-in spam protection with visible or managed modes
• 🍯 Honeypot Protection - Alternative spam protection using hidden form fields
• ❌ Dismissible Modal - Optional X button and click-outside-to-close
• 📱 Mobile-First Design - Optimized for touch interactions
• 🎯 TypeScript - Full type definitions included

Installation

npm install godgpt-web-waitlist

Peer Dependencies

This package requires React 18+ and Tailwind CSS:

npm install react react-dom

Tailwind CSS Setup

This component uses Tailwind CSS classes. Make sure Tailwind is configured in your project and add the package to your content paths:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/godgpt-web-waitlist/**/*.{js,ts,jsx,tsx}",
  ],
  // ...
};

Quick Start

import { WaitlistCard } from "godgpt-web-waitlist";

function App() {
  return (
    <WaitlistCard
      title="Join the Waitlist"
      subtitle="Be the first to know when we launch."
      onDone={() => console.log("Done!")}
    />
  );
}

Usage Modes

Uncontrolled Mode (Simple)

Let the component manage its own state. Great for quick implementations:

<WaitlistCard
  title="Join the Waitlist"
  subtitle="Enter your details below."
  actionUrl="https://your-api.com/subscribe"
  onDone={() => console.log("Success!")}
/>

Controlled Mode (Full Control)

Manage state externally for custom submission logic:

import { WaitlistCard, WaitlistFormData } from "godgpt-web-waitlist";

function App() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (data: WaitlistFormData) => {
    setIsSubmitting(true);
    setError(null);

    try {
      const response = await fetch("/api/subscribe", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(data),
      });

      if (!response.ok) {
        throw new Error("Subscription failed");
      }

      setIsSuccess(true);
    } catch (err) {
      setError("Something went wrong. Please try again.");
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <WaitlistCard
      title="Join the Waitlist"
      onSubmit={handleSubmit}
      isSubmitting={isSubmitting}
      isSuccess={isSuccess}
      error={error}
      onDone={() => setIsSuccess(false)}
    />
  );
}

Cloudflare Turnstile Integration

Visible Mode (Interactive Checkbox)

<WaitlistCard
  title="Secure Waitlist"
  turnstileSiteKey="your-site-key"
  turnstileTheme="light"
  onSubmit={(data) => {
    console.log("Token:", data["cf-turnstile-response"]);
  }}
  isSubmitting={isSubmitting}
  isSuccess={isSuccess}
/>

Managed Mode (Invisible)

For backend-managed Turnstile verification:

<WaitlistCard
  title="Join the Waitlist"
  turnstileSiteKey="your-site-key"
  turnstileManaged={true} // Hides the widget
  onSubmit={handleSubmit}
  isSubmitting={isSubmitting}
  isSuccess={isSuccess}
  error={error}
/>

Backend Verification

When using Turnstile, verify the token on your backend:

// Example: Cloudflare Pages Function
export async function onRequestPost({ request, env }) {
  const formData = await request.json();

  // Get token and IP
  const token = formData["cf-turnstile-response"];
  const ip = request.headers.get("CF-Connecting-IP");

  // Verify with Cloudflare
  const verifyResponse = await fetch(
    "https://challenges.cloudflare.com/turnstile/v0/siteverify",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        secret: env.TURNSTILE_SECRET_KEY,
        response: token,
        remoteip: ip,
      }),
    }
  );

  const result = await verifyResponse.json();

  if (!result.success) {
    return new Response(JSON.stringify({ message: "Verification failed" }), {
      status: 403,
    });
  }

  // Continue with subscription...
}

Note: Add the Turnstile script to your HTML:

<script
  src="https://challenges.cloudflare.com/turnstile/v0/api.js"
  async
  defer
></script>

Honeypot Integration

Honeypot is a lightweight spam protection alternative to Turnstile. It uses a hidden form field that bots typically fill but humans won't see.

Uncontrolled Mode with Honeypot

<WaitlistCard
  title="Join the Waitlist"
  subtitle="Enter your details below."
  honeypotFieldName="b_eecb4f508c0388d7720a99c82_0ad1109319" // Your honeypot field name
  actionUrl="https://your-api.com/subscribe"
  onDone={() => console.log("Success!")}
/>

Controlled Mode with Honeypot

import { WaitlistCard, WaitlistFormData } from "godgpt-web-waitlist";

function App() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const honeypotFieldName = "b_eecb4f508c0388d7720a99c82_0ad1109319";

  const handleSubmit = async (data: WaitlistFormData) => {
    // Check honeypot field
    const honeypotValue = data[honeypotFieldName];

    // If honeypot is filled, it's a bot - silently reject
    if (honeypotValue && honeypotValue.trim()) {
      console.log("Bot detected - honeypot field was filled");
      return; // Don't process, don't show error
    }

    setIsSubmitting(true);
    setError(null);

    try {
      const response = await fetch("/api/subscribe", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          EMAIL: data.EMAIL,
          FNAME: data.FNAME,
          LNAME: data.LNAME,
          // Include honeypot value for backend verification
          [honeypotFieldName]: honeypotValue || "",
        }),
      });

      if (!response.ok) {
        throw new Error("Subscription failed");
      }

      setIsSuccess(true);
    } catch (err) {
      setError("Something went wrong. Please try again.");
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <WaitlistCard
      title="Join the Waitlist"
      honeypotFieldName={honeypotFieldName}
      onSubmit={handleSubmit}
      isSubmitting={isSubmitting}
      isSuccess={isSuccess}
      error={error}
      onDone={() => setIsSuccess(false)}
    />
  );
}

Backend Verification

Always verify the honeypot on your backend:

// Example: Cloudflare Pages Function
export async function onRequestPost({ request, env }) {
  const formData = await request.json();

  const honeypotFieldName = "b_eecb4f508c0388d7720a99c82_0ad1109319";
  const honeypotValue = formData[honeypotFieldName];

  // If honeypot is filled, it's a bot - reject silently
  if (honeypotValue && honeypotValue.trim()) {
    // Return success to bot (don't reveal it's a honeypot)
    return new Response(JSON.stringify({ success: true }), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    });
  }

  // Process legitimate submission
  const { EMAIL, FNAME, LNAME } = formData;

  // Add to Mailchimp or your database
  // ...

  return new Response(JSON.stringify({ success: true }), {
    status: 200,
  });
}

How Honeypot Works

1. Hidden Field: The honeypot field is visually hidden using CSS (position: absolute; left: -5000px)
2. Bot Detection: Bots typically fill all form fields, including hidden ones
3. Silent Rejection: If the honeypot field is filled, the submission is rejected silently (no error shown)
4. Backend Check: Always verify on your backend as well for additional security

Note: The honeypot field name should match your Mailchimp embed form or your custom backend field name.

Props

Content

Prop	Type	Default	Description
title	string	"Join the Waitlist"	Modal title
subtitle	string	"Be the first to know..."	Description text
successTitle	string	"You're on the list!"	Success state title
successMessage	string	"Thank you for joining..."	Success state message

Uncontrolled Mode

Prop	Type	Description
actionUrl	string	URL to POST form data to

Controlled Mode

Prop	Type	Description
onSubmit	(data: WaitlistFormData) => void	Called with form data on submit
isSubmitting	boolean	Shows loading state
isSuccess	boolean	Shows success state
error	string | null	Error message to display

Mailchimp

Prop	Type	Description
tags	string	Hidden tag value for Mailchimp

Cloudflare Turnstile

Prop	Type	Default	Description
turnstileSiteKey	string	-	Enables Turnstile verification
turnstileTheme	"light" | "dark" | "auto"	"auto"	Widget theme
turnstileSize	"normal" | "compact"	"normal"	Widget size
turnstileAction	string	-	Action name for analytics
turnstileManaged	boolean	false	Hide widget (invisible mode)

Honeypot

Prop	Type	Description
honeypotFieldName	string	Name attribute for the honeypot field (e.g., Mailchimp field name)

Modal Behavior

Prop	Type	Default	Description
dismissible	boolean	false	Show X button, allow click-outside

Callbacks

Prop	Type	Description
onDone	() => void	Called when user clicks "Done" on success
onClose	() => void	Called when modal is dismissed

Form Data Structure

interface WaitlistFormData {
  EMAIL: string;
  FNAME: string;
  LNAME: string;
  "cf-turnstile-response"?: string; // Present if Turnstile enabled
  [key: string]: string | undefined; // Dynamic fields (e.g., honeypot field)
}

Note: When using honeypot, the field name will be whatever you pass to honeypotFieldName. For example, if honeypotFieldName="b_eecb4f508c0388d7720a99c82_0ad1109319", then data["b_eecb4f508c0388d7720a99c82_0ad1109319"] will contain the honeypot value.

Exports

// Components
export { WaitlistCard, WaitlistModal } from "godgpt-web-waitlist";

// Types
export type { WaitlistCardProps, WaitlistFormData } from "godgpt-web-waitlist";

// Sub-components (advanced usage)
export { Button, Input, Toast } from "godgpt-web-waitlist";

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build library
npm run build:lib

# Build demo app
npm run build

License

MIT