FormFlow Documentation

Beautiful React form components with a built-in backend. Add contact forms, newsletter signups, and feedback forms to your app in minutes.

Installation

Install the package using npm, yarn, or pnpm:

npm install @formflow.sh/react

Quick Start

FormFlow provides a useFormFlow hook that works with any UI library. It's built on react-hook-form and automatically submits to the FormFlow backend.

With Your Own Components (Recommended)

Use the hook with shadcn/ui, Material-UI, Chakra UI, or native HTML:

import { useFormFlow } from '@formflow.sh/react';
import { Input } from '@/components/ui/input'; // any UI library
import { Button } from '@/components/ui/button';

function ContactForm() {
  const { register, handleSubmit, formState } = useFormFlow({
    apiKey: process.env.NEXT_PUBLIC_FORMFLOW_API_KEY,
    onSuccess: () => alert('Form submitted!'),
  });

  return (
    <form onSubmit={handleSubmit} className="space-y-4">
      <Input {...register('email')} type="email" required />
      <Input {...register('name')} required />
      <textarea {...register('message')} required />
      <Button type="submit" disabled={formState.isSubmitting}>
        {formState.isSubmitting ? 'Sending...' : 'Submit'}
      </Button>
    </form>
  );
}

Pre-built Templates

Or use our pre-built components for quick setup:

import { ContactForm } from '@formflow.sh/react';

function App() {
  return (
    <ContactForm
      apiKey="ff_live_xxx"
      onSuccess={() => console.log('Form submitted!')}
    />
  );
}

Available Templates

FormFlow includes 6 pre-built form templates:

• ContactForm - Name, email, subject, and message fields
• NewsletterForm - Email signup with optional name field
• FeedbackForm - Star ratings or NPS scores with comments
• BookingForm - Service selection with date/time picker
• SupportTicketForm - Category, priority, and description
• QuoteRequestForm - Service selection with budget ranges

Themes

All templates support 4 built-in themes:

// Minimal (default) - Clean, subtle shadows
<ContactForm theme="minimal" />

// Modern - Rounded corners, gradient accents
<ContactForm theme="modern" />

// Brutalist - Bold borders, high contrast
<ContactForm theme="brutalist" />

// Glass - Frosted glass effect with blur
<ContactForm theme="glass" />

useFormFlow Hook API

The useFormFlow hook is the recommended way to build forms. It wraps react-hook-form and adds automatic backend submission.

Basic Usage

const { register, handleSubmit, formState } = useFormFlow({
  apiKey: 'your-api-key',
  onSuccess: (data, response) => {
    console.log('Submitted:', data);
    console.log('Response:', response);
  },
  onError: (error) => {
    console.error('Error:', error);
  },
});

With Validation

Built-in validation using react-hook-form patterns:

<input
  {...register('email', {
    required: 'Email is required',
    pattern: {
      value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
      message: 'Invalid email address'
    }
  })}
  type="email"
/>
{formState.errors.email && (
  <span className="error">
    {formState.errors.email.message}
  </span>
)}

Loading States

Access form state for loading indicators and disabled buttons:

<button type="submit" disabled={formState.isSubmitting}>
  {formState.isSubmitting ? 'Sending...' : 'Submit'}
</button>

Default Values

Initialize forms with default values:

const { register, handleSubmit } = useFormFlow({
  apiKey: 'your-api-key',
  defaultValues: {
    email: 'user@example.com',
    name: 'John Doe',
  },
});

Works with Any UI Library

The hook is UI-agnostic and works with any component library:

• shadcn/ui: <Input {...register("email")} />
• Material-UI: <TextField {...register("email")} />
• Chakra UI: <Input {...register("email")} />
• Native HTML: <input {...register("email")} />

Building Custom Forms (Legacy)

You can also use the wrapper components to build custom forms:

import {
  FormFlow,
  Input,
  Textarea,
  Select,
  Checkbox,
  SubmitButton
} from '@formflow.sh/react';

function CustomForm() {
  return (
    <FormFlow apiKey="ff_live_xxx">
      <Input name="email" type="email" label="Email" required />
      <Select
        name="plan"
        label="Select Plan"
        options={['Free', 'Pro', 'Enterprise']}
      />
      <Textarea name="message" label="Message" />
      <Checkbox name="terms" label="I agree to the terms" required />
      <SubmitButton>Submit</SubmitButton>
    </FormFlow>
  );
}

Pricing

Next Steps

• Browse the template documentation
• Learn about core components
• Set up webhooks for Slack, Discord, or custom integrations