Layout Group

A flexible multi-column layout container. Layout Group places its direct children side by side in 2, 3, or more columns with configurable widths, column gap, and an optional box model.

Overview

A Layout Group (layout_group) arranges its direct children as side-by-side columns. Each child occupies one column and can be any node type - most commonly a Section - allowing complex multi-column designs.

Unlike the Section's built-in layout: "2" mode (which always splits at the midpoint 50/50), a Layout Group gives full control over the number of columns, each column's individual width, and the gap between them.

Column Configuration

Columns are managed from the Column Width Controls panel in the Designer. Each column can be:

Width value	Behaviour
`star` (default)	Takes an equal share of the remaining space after fixed columns are subtracted. Two `star` columns produce 50/50. Three produce 33/33/33.
`0–100` (percentage)	Treated as a percentage of the total available page width (515 pt).

Columns can be added and removed dynamically. The column gap is shared equally between adjacent column pairs.

Automatic Label Width Capping

The actual point width of each column is computed at render time and threaded into child nodes so that nested label/value fields can automatically cap their label width to fit, preventing the document engine from collapsing the multi-column layout.

Column Layout Properties

Property	Type	Default	Description
`columns`	column array	`[]`	Ordered list of column definitions. Each entry has a `width` value (percentage `0–100` or `"star"`).
`columnGap`	`number`	`12`	Space (pt) between adjacent columns. Managed from the Column Width Controls panel.
`verticalAlign`	`select`	`top`	Vertical alignment of content within each column cell when cells have unequal heights. Options: `top`, `middle`, `bottom`.

Title

A Layout Group can display an optional group-level title above the columns.

Property	Type	Default	Description
`title`	`string`	none	Group heading text displayed above all columns. Supports `{FIELDNAME}` tokens.
`accentColor`	`color`	`theme.primary`	Color of the group title text.

Box Model

When fillColor or borderWidth is set the Layout Group renders using a table-based backend so that the fill and border are applied uniformly across all columns. Without these properties a lightweight columns layout is used instead.

Property	Type	Default	Description
`fillColor`	`color`	none	Background fill applied inside all column cells.
`padding`	`number`	`0`	Inner padding (pt) within each column cell.
`borderWidth`	`number`	`0`	Outer border thickness (pt). When `> 0`, inner column separators are suppressed - only the outer left, right, top, and bottom edges are drawn.
`borderColor`	`color`	`theme.borderColor`	Border color.
`marginTop`	`number`	`0`	Space above the Layout Group block (pt).
`marginBottom`	`number`	`8`	Space below the Layout Group block (pt).

Outer Border Without Dividers

To draw a shared border around all columns without drawing dividers between them, set borderWidth > 0 and leave padding at 0. The outer edge renders as a clean rectangle with no internal lines.

Sections Inside a Layout Group

A Section used as a direct column of a Layout Group is treated as a structural container rather than a nested subsection:

The depth-based left indent is suppressed - content starts flush with the column edge.
The accent pipe and title icon render at full strength, identical to a top-level section.
When showHeader is off and a title is set, the section gets the full plain-mode accent pipe treatment.
When showHeader is on, the section header row renders inside its column as expected.

Pagination

Property	Path	Description
`Break Before`	`pagination.breakBefore`	`never` / `always` / `whenOverflow`
`Break After`	`pagination.breakAfter`	`never` / `always`
`Keep Together`	`pagination.keepTogether`	Prevent the group from splitting across pages.

Conditional Visibility

Property	Path	Description
`Visible When`	`expressions.visibleWhen`	Expression evaluated at render time. The entire group (all columns) is omitted when falsy.

Examples

Two equal columns

{
  "type": "layout_group",
  "props": {
    "columns": [
      { "width": "star" },
      { "width": "star" }
    ],
    "columnGap": 12,
    "verticalAlign": "top"
  }
}

Narrow label + wide content (30 / 70 split)

{
  "type": "layout_group",
  "props": {
    "columns": [
      { "width": 30 },
      { "width": "star" }
    ],
    "columnGap": 12,
    "verticalAlign": "top"
  }
}

Three-column summary

{
  "type": "layout_group",
  "props": {
    "title": "Summary",
    "columns": [
      { "width": "star" },
      { "width": "star" },
      { "width": "star" }
    ],
    "columnGap": 12,
    "verticalAlign": "top"
  }
}

Bordered card (theme-driven)

Omit fillColor and borderColor to use the active theme. Provide hex values only when overriding.

{
  "type": "layout_group",
  "props": {
    "columns": [
      { "width": "star" },
      { "width": "star" }
    ],
    "columnGap": 16,
    "borderWidth": 0.5,
    "borderColor": "theme.borderColor",
    "padding": 10,
    "marginTop": 8,
    "marginBottom": 8
  }
}

Bordered card with custom fill

{
  "type": "layout_group",
  "props": {
    "title": "Approval Block",
    "accentColor": "#1E3A5F",
    "columns": [
      { "width": "star" },
      { "width": "star" },
      { "width": "star" }
    ],
    "columnGap": 12,
    "borderWidth": 0.5,
    "borderColor": "#CBD5E1",
    "fillColor": "#F8FAFC",
    "padding": 12,
    "marginTop": 12,
    "marginBottom": 4
  }
}

With conditional visibility

{
  "type": "layout_group",
  "props": {
    "columns": [
      { "width": "star" },
      { "width": "star" }
    ],
    "columnGap": 12
  },
  "expressions": {
    "visibleWhen": "showBillingDetails === true"
  }
}

Layout Group

On this page