When to use
- Long forms — registrations or applications that would overwhelm on a single screen.
- Forms with natural stages — details, then preferences, then consent.
For a short form, use Form Field blocks on their own.
Key decisions
- Structure: one Multi-Page Form block set to Form Configuration at the top of a section, then one set to Step at each step boundary, with Form Field blocks between them. At least two steps.
- Submission is the site's job: Submit emits multi-page-form:submit on window.Bus with the form ID, the action and every field's value. The site sends the request and reports back with multi-page-form:state-change.
- Validation: on blur, on step transition and on submit, all on by default. Keep On Submit at the least.
- Going back: with Allow Jumping to Completed Steps on, readers can click a completed tab to return to it.
Example
A two-step form. Complete step 1 to reach step 2.
All authoring options
Form Configuration (one per section)
role: form
formId: unique kebab-case id, sent with the submit event. Required
formAction: passed in the event payload; the block does not call it. Required
submitLabel: default "Submit"
successMessage: rich text that replaces the form on success. Required
errorMessage: banner text on error. Required
validationModes: blur | step | submit. Default all three
allowStepJump: boolean — click a completed tab to return to it. Default on
Step (one per step boundary)
role: step
stepHeader: the tab label. Required
stepDescription: optional rich text above the step's fields
previousLabel / nextLabel: default "Previous" / "Next"
Analytics
trackFormInview: emit an event when the form scrolls into view
trackStepTabClick: emit an event when a step tab is clicked
trackNextClick / trackPrevClick / trackSubmitClick: emit an event per button, each with its own meta field
meta: form-level analytics meta, sent as a JSON string
Events emitted:
emu-multi-page-form:inview
emu-multi-page-form:step-tab:click
emu-multi-page-form:next:click
emu-multi-page-form:prev:click
emu-multi-page-form:submit:click