Form Builder Guide

Master all 16 field types and create powerful AI forms with the visual form builder.

Form Builder Overview

Accessing the Form Builder

  1. Go to AI Agents > Edit Agent
  2. Scroll to AI Agent Form Builder meta box
  3. Choose your editing mode:
    • Visual Builder - Drag & drop interface
    • JSON Editor - Code-based editing
    • Preview - See how your form looks

Form Builder Interface

Visual Builder features:

  • ➕ Add Field button - Create new fields
  • 🔄 Drag handles - Reorder fields
  • ✏ī¸ Edit button - Modify field settings
  • 🗑ī¸ Delete button - Remove fields
  • 💾 Save Form button - Save your configuration

Basic Workflow

1. Click "Add Field"
   ↓
2. Choose field type
   ↓
3. Configure settings
   ↓
4. Click "Add to Form"
   ↓
5. Repeat for more fields
   ↓
6. Click "Save Form"

All 16 Field Types

WP AI Connector supports 16 powerful field types for building any form you need.

1. Text Field

Best for: Names, titles, short answers

Configuration

Label: "Your Name"
Field Type: Text
Placeholder: "Enter your full name"
Required: ✅ Yes
Min Length: 2
Max Length: 100
Default Value: (leave empty)
Help Text: "First and last name"

Use Cases

  • Full name
  • Company name
  • Job title
  • Short text answers

2. Email Field

Best for: Email addresses with validation

Features

  • ✅ Built-in HTML5 email validation
  • ✅ Server-side sanitization with sanitize_email()
  • ✅ Visual feedback for invalid emails

Configuration

Label: "Email Address"
Field Type: Email
Placeholder: "you@example.com"
Required: ✅ Yes
Help Text: "We'll send results here"
💡 Tip: Email validation ensures users enter valid email addresses before submission.

3. Number Field

Best for: Quantities, ages, ratings, prices

Configuration

Label: "How many images?"
Field Type: Number
Min: 1
Max: 10
Step: 1
Default: 3
Required: ✅ Yes
Help Text: "Between 1 and 10"

Use Cases

  • Quantity selection
  • Age input
  • Rating scales (1-5, 1-10)
  • Price ranges
  • Year selection
💡 Pro Tip: Use step="0.01" for decimal numbers like prices.

4. Phone Field

Best for: Phone numbers

Configuration

Label: "Phone Number"
Field Type: Phone
Placeholder: "+1 (555) 123-4567"
Pattern: [0-9]{3}-[0-9]{3}-[0-9]{4}
Required: ❌ No
Help Text: "Format: 123-456-7890"

Pattern Examples

  • US Format: [0-9]{3}-[0-9]{3}-[0-9]{4}
  • International: \+[0-9]{1,3}\s[0-9]{4,14}
  • Flexible: [0-9\s\-\(\)]+

5. Date Field

Best for: Event dates, deadlines, birthdays

Features

  • 📅 Browser date picker
  • ✅ Min/max date validation
  • 🌍 Locale-aware formatting

6. Time Field

Best for: Appointment times, scheduling

Features

  • 🕐 Visual time picker
  • ⏰ 12/24 hour format (based on locale)
  • ✅ Validates proper time format

7. DateTime Field

Best for: Complete date and time selection

Use Cases

  • Appointment scheduling
  • Event registration
  • Delivery slot booking
  • Meeting scheduler

8. Select Dropdown

Best for: Single choice from multiple options

Configuration

Label: "Choose AI Model"
Field Type: Select
Options:
  GPT-4 (Most Advanced)
  GPT-3.5 (Fast & Efficient)
  Claude 3 (Best for Analysis)
  Llama 2 (Open Source)
Required: ✅ Yes
Default: GPT-3.5 (Fast & Efficient)

Tips

  • ✅ Use clear, descriptive option names
  • ✅ Add help text for guidance
  • ✅ Set sensible default for common choice

9. Multi-Select

Best for: Multiple choices from list

Configuration

Label: "Select Features (hold Ctrl/Cmd)"
Field Type: Multi-Select
Options:
  Background Removal
  Color Correction
  Upscaling
  Style Transfer
  Face Enhancement
Size: 5 (shows 5 options at once)
Required: ❌ No
ℹī¸ Note: Values sent as array: ["Background Removal", "Upscaling"]

10. Radio Buttons

Best for: Single choice, all options visible

When to use Radio vs Select

  • Radio: 2-5 options, all should be visible
  • Select: 6+ options, save space

Configuration

Label: "Image Orientation"
Field Type: Radio
Options:
  Portrait (Vertical)
  Landscape (Horizontal)
  Square (1:1)
Default: Square (1:1)
Required: ✅ Yes
Layout: Horizontal

11. Checkboxes

Best for: Multiple choices, all visible

Configuration

Label: "Additional Options"
Field Type: Checkbox
Options:
  High Resolution (4K)
  Watermark Removal
  Commercial License
  Priority Processing
Required: ❌ No

Data Format: Array of selected values

12. Textarea

Best for: Long text, descriptions, multi-line input

Configuration

Label: "Describe your vision"
Field Type: Textarea
Rows: 6
Placeholder: "Be as detailed as possible..."
Required: ✅ Yes
Max Length: 1000
Help Text: "The more detail, the better the result!"

Use Cases

  • AI prompts
  • Detailed descriptions
  • Comments/feedback
  • Instructions
  • Stories/content
💡 Pro Tips:
  • Set rows="4" for short descriptions
  • Set rows="8" for detailed prompts
  • Use maxlength to prevent overly long input

13. File Upload

Best for: Images, documents, any file type

Features

  • 📁 Drag & Drop - Drag files onto area
  • 👁ī¸ Image Previews - See thumbnails before upload
  • 📊 File Icons - PDF, Word, Excel icons
  • ✅ Size Validation - 25MB per file, 100MB total
  • 🗑ī¸ Remove Files - Click X to remove
  • đŸ”ĸ Multiple Files - Upload several at once

Configuration

Label: "Upload Reference Image"
Field Type: File
Accept: image/png,image/jpeg,image/jpg,image/gif
Required: ❌ No
Help Text: "Upload an image as reference (Max 25MB)"

How It Works

  1. User uploads file
  2. File converted to base64
  3. Sent to webhook with metadata:
    • field_name_file_data: base64 content
    • field_name_file_name: original filename
    • field_name_file_type: MIME type
    • field_name_file_size: size in bytes
ℹī¸ See Also: Check the File Upload Guide for complete file processing examples.

14. Hidden Field

Best for: Passing data invisibly

Use Cases

  • User type/tier
  • UTM tracking
  • Session IDs
  • API keys (NOT recommended for security)
  • Default values
💡 Pro Tip: Use hidden fields to pass context to your webhook without showing it to users.

15. Section Header

Best for: Organizing long forms

Use Cases

  • Multi-step appearance
  • Group related fields
  • Break up long forms
  • Add visual hierarchy

Example Form Structure

Section: "Personal Info"
  ├─ Name (text)
  ├─ Email (email)
  └─ Phone (phone)

Section: "Project Details"
  ├─ Description (textarea)
  ├─ Budget (number)
  └─ Timeline (date)

16. HTML Content

Best for: Instructions, formatting, custom content

Use Cases

  • Instructions
  • Warnings/notices
  • Promotional content
  • Custom styling
  • Embedded videos
  • Pricing tables
⚠ī¸ Safety: HTML is rendered as-is, so ensure it's safe!

Form Validation

Client-Side Validation

Automatic HTML5 validation for:

  • ✅ Required fields
  • ✅ Email format
  • ✅ Number ranges (min/max)
  • ✅ Pattern matching
  • ✅ File size (JavaScript)
  • ✅ File type

Server-Side Validation

Automatic sanitization:

  • Text: sanitize_text_field()
  • Email: sanitize_email()
  • URL: esc_url_raw()
  • Numbers: Type casting
  • Files: MIME type check

Styling Your Forms

Default Styling

Forms come with clean, responsive styling out of the box.

Base CSS Classes

.ai-agent-form { }
.form-field { }
.field-label { }
.field-input { }
.field-help-text { }
.submit-button { }
.form-success { }
.form-error { }

Custom Styling

Add to your theme's style.css:

/* Custom form styling */
.ai-agent-form {
  max-width: 600px;
  margin: 0 auto;
  padding: 30px;
  background: #f9f9f9;
  border-radius: 10px;
}

.ai-agent-form .field-label {
  font-weight: 600;
  color: #333;
  margin-bottom: 8px;
}

.ai-agent-form .field-input {
  width: 100%;
  padding: 12px;
  border: 2px solid #ddd;
  border-radius: 6px;
  transition: border-color 0.3s;
}

.ai-agent-form .field-input:focus {
  border-color: #0066cc;
  outline: none;
  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.1);
}

.ai-agent-form .submit-button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 15px 40px;
  border: none;
  border-radius: 50px;
  font-size: 16px;
  font-weight: 600;
  cursor: pointer;
  transition: transform 0.2s;
}

.ai-agent-form .submit-button:hover {
  transform: translateY(-2px);
  box-shadow: 0 10px 20px rgba(0,0,0,0.2);
}

Form Examples

Example 1: AI Chatbot

{
  "fields": [
    {
      "label": "What can I help you with?",
      "type": "textarea",
      "placeholder": "Ask me anything...",
      "rows": 4,
      "required": true
    },
    {
      "label": "Response Style",
      "type": "radio",
      "options": [
        "Professional",
        "Casual & Friendly",
        "Technical & Detailed"
      ],
      "default": "Casual & Friendly",
      "required": true
    }
  ]
}

Example 2: Image Generation

{
  "fields": [
    {
      "label": "Describe what you want to create",
      "type": "textarea",
      "placeholder": "A futuristic city at sunset...",
      "rows": 4,
      "required": true,
      "help": "Be as detailed as possible for best results"
    },
    {
      "label": "Art Style",
      "type": "select",
      "options": [
        "Photorealistic",
        "Digital Art",
        "Oil Painting",
        "Watercolor",
        "Anime/Manga"
      ],
      "required": true
    },
    {
      "label": "Image Size",
      "type": "radio",
      "options": [
        "Square (1024x1024)",
        "Portrait (1024x1792)",
        "Landscape (1792x1024)"
      ],
      "default": "Square (1024x1024)",
      "required": true
    }
  ]
}

Example 3: Lead Generation Form

{
  "fields": [
    {
      "type": "section",
      "label": "Contact Information"
    },
    {
      "label": "Full Name",
      "type": "text",
      "required": true
    },
    {
      "label": "Email",
      "type": "email",
      "required": true
    },
    {
      "label": "Company",
      "type": "text",
      "required": true
    },
    {
      "type": "section",
      "label": "Project Details"
    },
    {
      "label": "Budget Range",
      "type": "select",
      "options": [
        "Under $5,000",
        "$5,000 - $10,000",
        "$10,000 - $25,000",
        "$25,000+"
      ],
      "required": true
    },
    {
      "label": "Project Description",
      "type": "textarea",
      "rows": 6,
      "required": true
    }
  ]
}

Tips & Best Practices

Field Organization

✅ DO:

  • Group related fields together
  • Use section headers for clarity
  • Start with most important fields
  • End with email/submit

❌ DON'T:

  • Mix unrelated fields
  • Create forms too long (>10 fields)
  • Put required fields at the end
  • Skip help text

Required Fields

Only mark as required if:

  • ✅ Absolutely necessary for processing
  • ✅ Can't have sensible default
  • ✅ User must make conscious choice

Don't require if:

  • ❌ It's just "nice to have"
  • ❌ You can infer from other fields
  • ❌ It reduces conversion rates

Help Text

Use help text to:

  • Explain format (e.g., "Format: 123-456-7890")
  • Set expectations (e.g., "Processing takes 30-60 seconds")
  • Provide examples (e.g., "Example: modern minimalist logo")
  • Clarify purpose (e.g., "We'll never share your email")

Next: Webhook Integration →

Connect your forms to n8n, Make, Zapier, and custom APIs

← Previous: Getting Started

Installation and creating your first agent