Forms 2.0 - Layouting
This page is preliminary and subject to change as Forms 2.0 continues to be developed.
Every Forms 2.0 layout is built from containers. The form itself is a container, and you arrange fields by choosing how each container lays out its contents, then nesting containers inside one another. This page explains how the three layout modes behave and shows how to combine them for common form designs. For dragging and resizing fields on the Canvas, see Canvas.
The form's root container
The form's top level is a container too - the root container. Click an empty area of the Canvas, outside any field, to select it and open its settings. It has the same layout settings as a Layout Container - Layout Mode, Columns, Alignment, Gap, Padding, and Root CSS Classes - but no visibility or enabled settings. Like every container, its Layout Mode, Alignment, Gap, and Padding can have a different value for each form width - see Different layouts for different widths.
The root container's label is shown as the title at the top of the Canvas.
Inside the root, you can add four kinds of container. Each has the same layout settings:
- Layout Container - for arranging fields. It has no title and no value.
- Section - groups related fields under a title, and gives them one value.
- Dynamic Container - receives fields added when the form loads (see Dynamic Forms).
- Repeater - repeats its layout once for each entry.
Layout modes
Each container lays out its fields on a grid of 12 columns, in one of three modes. A new container starts in Vertical.
Vertical
One field per row, each the full width of the container, in the order they appear on the Canvas.
Alignment (Left, Center, or Right) affects only fields that don't stretch - in practice, a Button with Button Width set to Fit to Content. Other fields always fill the row. Nested containers in a Vertical container also stretch to the full width.
Horizontal
Fields are placed side by side, left to right, and share the row's width equally - two fields get half each, three get a third each. When a row runs out of columns, the next field starts a new row. Each field needs at least one of the 12 columns, so a row holds at most 12 fields.
A Fit to Content button takes only a narrow slot, and the other fields in the row share the rest of the width. A Full Width button shares the row like any other field.
Alignment (Top, Middle, or Bottom) sets how fields of different heights line up within a row. The default is Bottom, so the inputs stay in line even when one field has a longer, wrapping label or a hint. With Bottom, the inputs also stay lined up when one field shows a validation message.
You can't set widths in Horizontal mode - every field in a row gets the same share. For uneven widths, use Manual.
Manual
A free-form grid: you place each field where you want it and set its width by resizing it on the Canvas (see Rearranging fields). Positions are saved with the form, so the live form matches the Canvas.
Columns sets how many columns the grid has. The default is 12. Fewer columns make placement coarser and easier - with 4 columns, every field is a quarter, half, three quarters, or the full width. A field is never wider than the grid, and it's moved left if it would overflow the right edge.
Height isn't set by you. Each row is as tall as its tallest field.
Switching modes
You can change a container's Layout Mode at any time. Switching to Vertical restacks its fields in order, one per row. Switching to Horizontal repacks them into rows. Switching to Manual starts from their current positions, so a common way to lay out a Manual container is to arrange the fields roughly in Vertical or Horizontal mode first, then switch to Manual and adjust.
Spacing
| Setting | Description |
|---|---|
| Gap | The space between the fields in the container: Compact (0.5rem), Normal (1rem, the root's default), or Loose (1.5rem). Nested containers default to Inherit, using their parent's gap. |
| Padding | Space inside the container's edges, in CSS units - for example 8px 0px (the default: 8px top and bottom, none at the sides) or 16px. |
Use a smaller gap inside a nested container to keep related fields, like the parts of an address, visibly grouped, while sections stay further apart.
Combining containers
Most layouts are a Vertical root with nested containers for the parts that need columns. Containers can be nested as deeply as you need, and each one has its own mode.
Two columns
To get two side-by-side columns of fields:
- Leave the root container in
Verticalmode. - Add a Layout Container in
Horizontalmode. - Inside it, add two Layout Containers in
Verticalmode, and drag each column's fields into one of them.
Each column then stacks its own fields, and the columns can be different lengths. Add a third inner container for three columns.
A row of related fields
Put the fields that belong on one line - First Name and Last Name, or Start Date and End Date - in a Layout Container in Horizontal mode, inside an otherwise Vertical form. Each such container is one row.
Uneven widths
For a row like City, State, and Zip, where City should be wider, use a Layout Container in Manual mode. With Columns set to 4, give City a width of 2 and State and Zip 1 each.
Sections with headings
To give a group of fields a heading, use a Section. Its Label is shown as the title above its fields while Show Title is on. A Section has the same layout settings as a Layout Container, so it can arrange its own fields in any mode. Add a class in its Root CSS Classes to style it, for example with a border or background - see Styling with CSS.
A Section also prefixes the names of its fields, for example [Billing:City]. If you only want a heading over fields that keep their own names, put a Content Block at the top of a Vertical Layout Container instead, because a Layout Container doesn't show its label.
Showing and hiding a whole section
A container's Visibility settings apply to everything inside it (see Common Field Settings), so you can show or hide a whole section with one rule on its container.
A hidden field or container keeps its space unless Remove From Layout When Not Visible is on. Leave it off when the space should stay reserved so the fields around it don't move. Turn it on when the rest of the form should close up the gap.
Buttons
- A single button on the right: put it in a Vertical container with Alignment set to
Right, and Button Width set toFit to Content. - Buttons side by side: put them in a Horizontal container with Button Width
Fit to Content. They sit together at the left of the row. - A full-width button, for example on a mobile-first form: set Button Width to
Full Width.
Different layouts for different widths
A container's layout doesn't change by itself on small screens. A Horizontal or Manual container keeps its columns on a phone too, with each column getting narrower. To change the layout at smaller widths, give the container's settings a different value for each width.
Layout Mode, Alignment, Gap, and Padding can each have three values: one for Narrow forms (under 768 px wide), one for Medium (768 to 1199 px) and one for Wide (1200 px and over). The width is the width of the form itself, not of the browser window. A form in a narrow column of a wide page uses its Narrow values.
The most common use: set a two-column container to Horizontal for Medium and Wide, and Vertical for Narrow, so its fields stack on phones.
See Responsive for how to set these values and preview them.
Styling with CSS
Every container's root element gets these classes, which you can target from your site's CSS:
| Class | Example | Description |
|---|---|---|
paa-container | paa-container | On every Layout Container and Dynamic Container. Sections use paa-section and Repeaters paa-repeater instead, with the same pattern for the classes below, for example paa-section-name-billing. |
paa-container-name-<name> | paa-container-name-addresscontainer | The container's Name, lowercased, with spaces replaced by hyphens. |
paa-container-<mode> | paa-container-horizontal | The container's Layout Mode: vertical, horizontal, or manual. |
Plus any classes you add in Root CSS Classes. Prefer your own classes in Root CSS Classes for styling, since they don't change if the container is renamed.
The form's root also gets paa-width-narrow, paa-width-medium, or paa-width-wide, depending on the form's current width. Use it to style the form differently at each width, for example .paa-width-narrow .my-panel { padding: 0; }.
Related
- Canvas - dragging, resizing, and previewing widths
- Layout Container, Section, Dynamic Container, and Repeater - the container field types
- Responsive - different layouts for different form widths
- Common Field Settings - visibility settings for containers and fields
Last updated: November 18, 2026