Layout and steps

By default every field is full width, one under another. Three tools change that: column puts fields side by side, section fields group fields under a heading, and steps split the form into pages with Next and Previous buttons. You can combine all three.

When to use it

Columns for short, related fields: first and last name, city and postcode.
Sections when a long form has distinct parts, such as “Your details” and “About the job”.
Steps when a form is long enough to put people off, or when later questions depend on earlier ones.

Columns

Give each field a column width: "1/2", "1/3", "2/3", "1/4" or "3/4", always as a string.

{"key": "first_name", "type": "text", "label": "First name", "column": "1/2"},
{"key": "last_name", "type": "text", "label": "Last name", "column": "1/2"},
{"key": "email", "type": "email", "label": "Email"}

Consecutive fields with a column share a row. When their widths add up to more than a full row, the next field wraps to a new line. A field without column ends the row. When the form is narrower than 400 pixels, as on a phone, every field goes full width.

Sections

A section is a field of type section. The fields that belong to it name its key in section, and must come directly after it in the list:

{"key": "your_details", "type": "section", "label": "Your details",
 "description": "So we can get back to you."},
{"key": "name", "type": "text", "label": "Name", "section": "your_details"},
{"key": "email", "type": "email", "label": "Email", "section": "your_details"}

The section shows its label as a heading and its description below it. The group ends at the first field that does not name the section. Columns work inside a section. Setting "appearance": {"surface": "card"} on the form removes the sections’ own card styling so cards are not nested.

Multi-step forms

Add a steps list at the top level, each with a key and a title.
Give every field a step naming one of those keys.

{
  "steps": [
    {"key": "contact", "title": "Your details"},
    {"key": "project", "title": "The project"}
  ],
  "fields": [
    {"key": "name", "type": "text", "label": "Name", "required": true, "step": "contact"},
    {"key": "email", "type": "email", "label": "Email", "required": true, "step": "contact"},
    {"key": "details", "type": "textarea", "label": "Details", "step": "project"}
  ],
  "settings": {
    "multistep": {"progress_style": "steps", "validate_on_next": true}
  }
}

Steps appear in the order listed. The last step has the submit button. A visitor can go back with Previous, or by selecting an earlier step in the progress indicator.

Options

These go in settings.multistep.

Option	What it does	Default
`show_progress`	Show the progress indicator above the steps.	`true`
`progress_style`	`steps` (numbered circles with step titles), `bar` (a bar with “Step 1 of 3”) or `dots`.	`steps`
`validate_on_next`	Check the current step’s fields before Next moves on.	on (off up to version 1.10.0)
`show_step_titles`	Also show each step’s title as a heading inside the step.	`false`

With progress_style set to steps, the indicator changes to the bar when the form is too narrow to fit every step’s number and title.

Limits and common problems

A field without step in a multi-step form is not shown at all.
A field in a section is shown outside it when another field sits between it and the section. Keep a section’s fields together.
Radio buttons and checkboxes ignore column up to version 1.10.0 and take the full width. From version 1.10.1 they follow it like other fields.
Steps and conditions. A step whose fields are all hidden by conditions still appears as an empty step.