formbuilder-plugin-group

A Group field type for formBuilder that bundles any number of registered child fields into a single, optionally-repeatable set.

▶ Live demo

Features

• Drag a single Group field onto the builder stage — the whole set moves as one unit.
• Inline child-field picker: add, reorder (drag handle), duplicate, or remove child fields without leaving the builder.
• Per-child edit panels powered by the formBuilder edit-panel hook (see Requirement below).
• Clean nested serialisation: getData() returns fields as a proper JSON array, not a stringified blob.
• formRender support: static rendering and repeatable instances with Add / Remove buttons, enforced min / max, and bracket-style child input naming (group[0][child]).

Requirement: formBuilder with edit-panel hook

The editor's per-child edit panels rely on a core hook (generateAdvFields / getAttrVals / updatePreview / stage.fbInstance) that is not yet in the published npm package. It will ship with formBuilder >= 3.23.0.

Until that release:

1. Clone and build the patched formBuilder branch locally:

   git clone https://github.com/kevinchappell/formBuilder.git ~/Dev/formBuilder
   cd ~/Dev/formBuilder
   git checkout feat/edit-panel-hook
   npm install
   npm run build:dev       # produces dist/form-builder.min.js

2. In your project, reference that local build instead of the npm package:

   <script src="/path/to/formBuilder/dist/form-builder.min.js"></script>

   or, if you use a bundler, set up a path alias / npm link.

formRender (rendering only, no editor) works with the published npm package and does not require the hook.

Installation

npm install formbuilder-plugin-group

Or download dist/group.umd.js and include it via a <script> tag.

Usage

Script tag (UMD)

<!-- 1. jQuery -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<!-- 2. formBuilder WITH edit-panel hook (see Requirement above) -->
<script src="/path/to/form-builder.min.js"></script>
<!-- 3. Group plugin — must load AFTER formBuilder -->
<script src="node_modules/formbuilder-plugin-group/dist/group.umd.js"></script>

<div id="build"></div>
<script>
  const fb = $('#build').formBuilder()
</script>

For formRender only (no editor):

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="node_modules/formBuilder/dist/form-render.min.js"></script>
<script src="node_modules/formbuilder-plugin-group/dist/group.umd.js"></script>

<form id="form"></form>
<script>
  $('#form').formRender({
    formData: [
      {
        type: 'group',
        name: 'address',
        label: 'Address',
        repeatable: true,
        min: 1,
        max: 3,
        addLabel: 'Add another address',
        fields: [
          { type: 'text', name: 'street', label: 'Street' },
          { type: 'text', name: 'city',   label: 'City'   },
        ],
      },
    ],
  })
</script>

ESM (bundler)

import 'formbuilder-plugin-group'   // registers the control via window.fbControls
import $ from 'jquery'

const fb = $('#build').formBuilder()

Styles

Styles are bundled into the plugin script and injected automatically when it loads — there is no separate stylesheet to include. To customise, override the .group-editor, .group-child, .fb-group, and .fb-group-instance classes in your own CSS after the plugin loads.

Group field options

These options appear in the formBuilder edit panel for a Group field and are also accepted directly in formData / formRender.

| Option | Type | Default | Description | |---|---|---|---| | label | string | "Group" | Human-readable label shown above the group. | | name | string | auto | Field name; used as the bracket-notation prefix for child inputs in formRender (name[i][child]). | | repeatable | boolean | false | When true, the rendered group shows Add / Remove buttons so users can create multiple instances. | | min | number | 1 | Minimum number of instances (only relevant when repeatable: true). Remove is disabled when the instance count equals min. | | max | number | (none) | Maximum number of instances (only relevant when repeatable: true). Add is disabled when the instance count equals max. Leave empty for unlimited. | | addLabel | string | "Add another" | Label text for the Add-instance button in formRender. | | fields | array | [] | Child field configurations (serialised as a JSON array). Managed via the inline editor in formBuilder; pass directly in formData for formRender. |

v1 Non-goals

The following features are intentionally out of scope for v1 and will not be implemented without a new major design:

• Nested groups — a Group field cannot contain another Group field. The child-field picker explicitly excludes group from the list of available types.
• Per-child grid / column layout — all child fields stack vertically within a group instance; custom grid positioning of individual children is not supported.
• Alternative naming schemes — child input names always use bracket notation (group[i][child]). Dot-notation or flat naming are not configurable.
• Group-level value binding — the value and placeholder attributes are disabled on the group control itself; values live in the individual child fields.

Development

npm install
npm run build   # produces dist/group.mjs + dist/group.umd.js
npm test        # unit + integration tests via Vitest
npm run lint    # ESLint

Demo pages in demo/ load the UMD build directly; see demo/MANUAL-VERIFICATION.md for the human browser-verification checklist.

License

MIT