Form Field Groups

A twenty-field form rendered as one flat column asks the submitter to read every input before understanding any of them. The same fields under three headings — "About you", "Your experience", "Why us" — become something a person can scan and answer a section at a time.

fieldGroups declares those headings. Each entry is a label plus the field names that belong under it:

forms:
  - id: 1
    name: apply
    title: Apply for Senior Engineer
    submitTo: { table: candidates }
    fieldGroups:
      - label: About you
        fields: [first_name, last_name, email]
      - label: Your experience
        fields: [years_of_experience, github_url]
    fields:
      - { kind: table-field, column: first_name, required: true }
      - { kind: table-field, column: last_name, required: true }
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: years_of_experience, inputType: number }
      - { kind: standalone, name: github_url, inputType: url }

Group Properties

fieldGroups is itself optional. Omit it and the form renders fields[] top to bottom with no headings — which is the right choice for a form short enough not to need signposting. When present, the array must declare at least one group.

Order Comes From the Groups

Once fieldGroups exists, it drives layout: sections render in array order, and each field renders in the position its group gives it. That means grouping can reorder a form without touching fields[] — the fields[] array keeps defining what the fields are, the groups define where they appear.

A field you never list still renders. It falls through to the bottom, after every section, in fields[] source order. Grouping half a form is therefore valid: the named fields get headings, the rest trail behind as an unlabeled block.

Conditional Sections

visibleWhen gates an entire section — label and every field under it — on the value of another field, using the same condition primitive as field-level rules:

fieldGroups:
  - label: Preferences
    fields: [wants_relocation]
  - label: Relocation
    fields: [relocation_country, relocation_date]
    visibleWhen: { field: wants_relocation, operator: eq, value: true }

The rule is evaluated server-side. On first render there are no answers yet, so a conditional section starts hidden and appears once its trigger is answered. On submit the rule is evaluated again, this time against the submitted values, and a section whose rule is false is treated as if it were never part of the form: its required fields do not block the submission.

Groups Versus Steps

Both carve a form into parts, and both take a visibleWhen. The difference is what the submitter sees at once.

Related Pages

• Form Fields — the fields[] entries a group refers to by name.
• Conditional Logic — the operator vocabulary visibleWhen draws on.
• Multi-Step Forms — steps[], the multi-screen alternative to groups.
• Forms Overview — where fieldGroups sits in the full form schema.