formforge-react

The official React SDK for FormForge—the state-of-the-art developer-first headless form API and real-time conversion telemetry platform. Easily back your custom frontend designs with high-throughput security filters, drop-off logs, and instant webhook dispatches.

🚀 Installation

npm install formforge-react

✨ Core Features

• 🎨 100% Styling Freedom: Style form elements using CSS, Tailwind, or any React UI library.
• 🛡️ Shielded Bot Filtering: Native velocity controls block rapid bot scripts silently.
• 🍯 Invisible Honeypots: Traps scrapers without forcing annoying CAPTCHAs.
• 📊 Real-time Conversion Telemetry: Monitors dynamic field focus events to map user drop-off funnels in your developer console.

💻 Quick Start Usage

1. Build a fully custom form using the useFormForge hook

The custom React hook manages active telemetry sessions, handles dynamic input interactions, processes bot velocity limits, and routes submissions asynchronously.

import React from 'react';
import { useFormForge } from 'formforge-react';

export default function LeadCapture() {
  const { handleSubmit, trackFieldFocus, loading, error, isBot } = useFormForge({
    formId: 'YOUR_FORM_ID_FROM_DASHBOARD',
    onSuccess: (result) => {
      console.log('Submission saved successfully!', result);
    },
    onError: (err) => {
      console.error('Submission failed:', err);
    }
  });

  if (isBot) {
    return (
      <div className="p-6 text-center bg-yellow-50 text-yellow-800 rounded-xl">
        ⚠️ Telemetry flagged this request. Submission completes silently.
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit} className="space-y-4 max-w-md mx-auto">
      {error && <div className="text-red-500 text-xs font-bold">Error: {error}</div>}

      {/* Invisible Honeypot Spam Trap (leave styled as display:none) */}
      <input type="text" name="website_url" style={{ display: 'none' }} tabIndex={-1} autoComplete="off" />

      <div>
        <label className="text-xs uppercase font-bold text-gray-500">Full Name</label>
        <input 
          type="text" 
          name="name" 
          required 
          onFocus={() => trackFieldFocus('Name')} 
          className="w-full px-3 py-2 border rounded-lg focus:outline-none"
        />
      </div>

      <div>
        <label className="text-xs uppercase font-bold text-gray-500">Email Address</label>
        <input 
          type="email" 
          name="email" 
          required 
          onFocus={() => trackFieldFocus('Email')} 
          className="w-full px-3 py-2 border rounded-lg focus:outline-none"
        />
      </div>

      <button type="submit" disabled={loading} className="w-full py-2.5 bg-black text-white font-bold rounded-lg text-sm">
        {loading ? 'Saving Lead...' : 'Submit Form'}
      </button>
    </form>
  );
}

2. Drop in the pre-styled FormForgeForm Widget

For instant setup, drop in the high-fidelity FormForge component. It automatically queries your form's schema from our API, renders styled inputs, manages telemetry, and displays success banners.

import React from 'react';
import { FormForgeForm } from 'formforge-react';

function App() {
  return (
    <div className="max-w-md mx-auto py-8">
      {/* Supports 'light' and 'dark' themes */}
      <FormForgeForm 
        formId="YOUR_FORM_ID_FROM_DASHBOARD" 
        theme="light" 
      />
    </div>
  );
}

export default App;

🛡️ Anti-Spam Design Notes

• The Honeypot (website_url): Bots scan standard DOM fields and auto-populate all text inputs. By leaving a hidden website_url field, we isolate automated scripts instantly.
• Velocity Check: Real humans take time to read, type, and navigate. If a submission completes in under 1.8 seconds, FormForge flags the session as a spambot and keeps your active dashboard database pristine.

📄 License

MIT © FormForge Team