Quick Start

Build your first dynamic form in 5 minutes.

Step 1: Import the Component

tsx

"use client"; // For Next.js App Router

import FormBuilderV3 from '@seanblock/form-builder';

Step 2: Create Your Form Configuration

Forms are defined using JSON. Here's a simple contact form:

tsx

const config = {
  id: "contact-form",
  type: "form",
  initialPage: "contact",
  pages: {
    contact: {
      id: "contact",
      blockType: "PageBlock",
      blocks: [
        {
          id: "content",
          blockType: "PageContentBlock",
          blocks: [
            {
              id: "name",
              blockType: "InputBlock",
              metadata: {
                label: "Your Name",
                placeholder: "Enter your name",
                contextPath: "user.name"
              },
              validations: [
                {
                  rule: "charMinLength",
                  value: 2,
                  message: "Name must be at least 2 characters"
                }
              ]
            },
            {
              id: "email",
              blockType: "InputBlock",
              metadata: {
                label: "Email Address",
                placeholder: "you@example.com",
                contextPath: "user.email"
              }
            },
            {
              id: "submit",
              blockType: "ButtonBlock",
              metadata: {
                label: "Submit"
              },
              actions: [
                {
                  type: "log",
                  message: "Form submitted!"
                }
              ]
            }
          ]
        }
      ]
    }
  }
};

Step 3: Render the Form

tsx

export default function ContactForm() {
  const initialContext = {
    user: {
      name: "",
      email: ""
    }
  };

  return (
    <div className="container mx-auto p-8">
      <FormBuilderV3 
        config={config} 
        context={initialContext}
        showDebug={true} // Enable debug panel during development
      />
    </div>
  );
}

Understanding the Structure

Key Concepts:

•
Pages: Forms are organized into pages for multi-step workflows
•
Blocks: Everything is a block - pages, inputs, buttons, containers
•
Context: Form data is stored in a shared context object
•
contextPath: Use dot notation to store data (e.g., "user.name")
•
Validations: Add validation rules to any input block
•
Actions: Define behaviors on events (click, change, etc.)

Common Block Types

Block Type	Purpose
PageBlock	Top-level page container
PageContentBlock	Main content area of a page
InputBlock	Text input field
SelectBlock	Dropdown select
CheckboxBlock	Checkbox input
ButtonBlock	Button for navigation/actions
CardBlock	Content card container
RowBlock	Horizontal layout

🎉

You're Ready!

You now know the basics of the form builder. Here's what to explore next: