FormWork FormWork

FormWork documentation

Form Structure

Build forms from pages, fields, groups, and repeatable instances.

A form version is a tree: pages contain fields, and groups or templated fields can contain subfields. Start with a flat, single-page form; add structure only when it improves the respondent’s experience or the shape of the data.

Form
└── Version
    ├── Page
    │   ├── Answer field
    │   ├── Content field
    │   └── Group
    │       └── Nested fields
    ├── Workflows
    ├── Settings
    └── Appearance

Work in the builder

The builder navigation contains:

  • Fields — pages, fields, default values, validation, and display logic
  • Metafields — admin-only companion fields
  • Workflows — triggers, steps, and connections
  • Appearance — saved colours, type, spacing, and theme mode
  • Settings — internal and respondent-facing text
  • Share — direct links and embed code

Draft changes autosave after a short delay. Use Preview to test and Publish to make the draft live.

Pages

Pages are respondent steps. A new form starts with page1, titled Page 1.

In the page manager you can:

  • Add a page
  • Edit its title
  • Reorder pages
  • Delete a page
  • Add display logic to show or hide it

Page IDs are stable machine names. Page titles are visible navigation/headings and can change without changing references.

Move pages with the up/down controls. FormWork will not delete the final remaining page, and it asks for confirmation before deleting a page that still contains fields. While dragging a field, another page’s tab becomes a drop target, so you can move the field between pages without rebuilding it.

Use multiple pages when a form has distinct stages or enough fields that one screen feels dense. A hidden page is skipped in client navigation.

Add and arrange fields

Select Add Field, choose a type, and accept the generated ID or enter a custom one. Once created, drag fields to reorder them or move them into compatible containers.

A field can be:

  • Top level, directly on a page
  • Nested, inside a Group
  • System-managed, generated inside Name or Address
  • Repeatable, with one or more ordered instances

You cannot change a field’s type or ID after creation. You can freely change its label and other supported settings.

Field ID rules

Custom field IDs use lower snake case: letters, numbers, and underscores, beginning with a letter. Examples: email, billing_address, line_items.

IDs drive answer paths, references, imports, exports, and integrations. Prefer durable business names rather than visual position such as question_3.

Groups and nesting

A Group contains user-defined child fields and can lay them out in a column or responsive row.

Contact details (group)
├── first_name
├── last_name
└── email

Groups are useful when children belong to one logical object, especially when the group will be repeated. Avoid nesting simply for visual decoration; it also changes answer paths.

Name and Address are templated fields. FormWork creates and manages their children based on the switches you choose, such as middle name or postcode. Those generated children cannot be managed as ordinary group children.

Repeatable fields

Turn on Repeatable for an eligible field when the respondent needs an ordered list of values or objects.

  • A repeatable text field collects several text instances.
  • A repeatable group collects several structured rows.
  • Show first instance creates the first item immediately; otherwise the respondent begins with an Add action.

Respondents can add, remove, and reorder instances. Each has a stable instance ID, so changing the order does not change its answer paths.

line_items[item_a].description
line_items[item_a].quantity
line_items[item_b].description
line_items[item_b].quantity

The parent line_items answer stores the ordered instance IDs. Default Array mapping can generate repeatable instances from a source collection.

How answers are stored

Entries use a flat answer map, even though the schema is a tree:

{
  "email": "[email protected]",
  "address.city": "Leeds",
  "line_items[item_a].quantity": 2
}

Use the reference picker for normal configuration. Hand-written paths are mainly relevant to the API and advanced templates; see References & Data.

A reliable building order

  1. Sketch the pages and groups.
  2. Add fields and choose stable IDs.
  3. Configure field-specific controls in Field Settings.
  4. Add defaults, validation, and display logic.
  5. Configure Form Settings and Appearance.
  6. Preview every route through the form.
  7. Publish the validated draft.

For the 27 available types, use Field Types.