Skip to main content
Version: 1.28 (Current)

Forms 2.0 - Layouting

caution

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.

The root container's label is shown as the title at the top of the Canvas.

Inside the root, you can add three kinds of container. Each has the same layout settings:

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​

SettingDescription
GapThe 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.
PaddingSpace 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:

  1. Leave the root container in Vertical mode.
  2. Add a Layout Container in Horizontal mode.
  3. Inside it, add two Layout Containers in Vertical mode, 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.

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​

Containers don't show their label on the live form. To give a group of fields a heading, put a Content Block at the top of a Vertical Layout Container, followed by the section's fields. Add a class in the container's Root CSS Classes to style the section, for example with a border or background - see Styling with CSS.

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 to Fit 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.

On small screens​

When the browser window is narrower than 768px, every container shows its fields in a single column, whatever its Layout Mode. Fields stack in their Canvas order - for Manual containers, row by row, left to right. Forms stay usable on phones without a separate layout.

This depends on the width of the browser window, not the width of the form. A form placed in a narrow column of a wide page keeps its columns. The Canvas width toggle previews the form at different form widths, but it doesn't show the single-column phone layout. Check that on a phone or a narrow browser window.

See Responsive for more on how forms adapt to different screens.

Styling with CSS​

Every container's root element gets these classes, which you can target from your site's CSS:

ClassExampleDescription
paa-containerpaa-containerOn every Layout Container and Dynamic Container. Repeaters use paa-repeater instead.
paa-container-name-<name>paa-container-name-addresscontainerThe container's Name, lowercased, with spaces replaced by hyphens.
paa-container-<mode>paa-container-horizontalThe 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.