Form Structure

Understand how forms are organized with pages, fields, and nested structures.

Forms in FormWork are organized in a hierarchical structure that supports simple single-page forms as well as complex multi-step experiences.

Form Hierarchy

Form
└── Form Version (draft or published)
    └── Pages
        └── Fields
            └── Subfields (for groups and templated fields)

Pages

Pages are top-level containers that organize your form into logical sections.

Single-Page Forms

The simplest forms have just one page containing all fields. Users see everything at once and submit in one step.

Multi-Page Forms

For longer forms, split content across multiple pages:

• Improve user experience with manageable chunks
• Show progress through the form
• Allow saving progress between pages

Creating Pages

1. In the form builder, click Add Page
2. Give the page a title
3. Drag fields into the page
4. Reorder pages by dragging the page tabs

Page Properties

Fields

Fields are the building blocks of your forms. Each field collects or displays information.

Field Organization

Fields can be:

• Top-level - Directly on a page
• Nested - Inside a group or container field
• Repeatable - Inside a repeating group

Field Properties

Common properties for all fields:

Field IDs

Every field has a unique ID used to:

• Reference the field in conditional logic
• Access answers in workflows
• Target fields in the API

IDs must:

• Contain only lowercase letters, numbers, and underscores
• Start with a letter
• Be unique within the form

Container Fields

Some fields contain other fields, creating nested structures.

Groups

Group fields organize related fields together visually and logically.

Contact Information (Group)
├── First Name (Text)
├── Last Name (Text)
└── Email (Email)

Group properties:

• Layout - row or column arrangement
• Fields - Nested field definitions

Repeatable Groups

Make any group repeatable to allow multiple entries:

Order Items (Repeatable Group)
├── Product Name (Text)
├── Quantity (Number)
└── Price (Number)

Users can:

• Add new instances
• Remove instances
• Reorder instances

Templated Fields

Some field types automatically generate subfields:

Name Field:

Full Name (Name)
├── Title (Text) - optional
├── First Name (Text)
├── Middle Name (Text) - optional
└── Last Name (Text)

Address Field:

Address (Address)
├── Street (Text)
├── Street 2 (Text) - optional
├── City (Text)
├── State (Text)
├── Postcode (Text)
└── Country (Select)

Answer Paths

When an entry is submitted, answers are stored with paths that reflect the structure:

Simple Fields

email → "[email protected]"

Nested Fields

contact.first_name → "John"
contact.last_name → "Smith"

Repeatable Fields

Each instance gets a unique ID:

items[abc123].name → "Widget"
items[abc123].quantity → 5
items[def456].name → "Gadget"
items[def456].quantity → 3

Deep Nesting

Paths can go as deep as your structure:

sections[s1].questions[q1].options[o1].label → "Option A"

Form Schema

Internally, form structure is stored as JSON:

{
  "pages": [
    {
      "id": "page1",
      "title": "Contact Info",
      "fields": [
        {
          "id": "name",
          "type": "text",
          "label": "Your Name",
          "required": true
        },
        {
          "id": "contact",
          "type": "group",
          "label": "Contact Details",
          "layout": "row",
          "fields": [
            {
              "id": "email",
              "type": "email",
              "label": "Email"
            },
            {
              "id": "phone",
              "type": "phone",
              "label": "Phone"
            }
          ]
        }
      ]
    }
  ]
}

Best Practices

Logical Grouping

Group related fields together for better UX and easier data management.

Consistent Naming

Use clear, consistent ID naming conventions across forms.

Page Length

Keep pages focused - too many fields on one page can overwhelm users.

Nesting Depth

Avoid excessive nesting - deep structures can be confusing to navigate.