Section

The primary content container in VaultPDF. Sections group related fields and controls, provide titled regions with optional accent pipes and icons, and support a full box model for borders, fills, and header rows.

Overview

A Section (section) is the top-level grouping unit in every VaultPDF template. It wraps related controls into a visually coherent block that can optionally carry a title, an accent pipe, an icon, a colored header row, and a complete box model (fill, border, padding, margin).

Sections can be nested. A section placed inside another section renders as a subsection with proportional font size reduction. A section placed directly inside a Layout Group is treated as a structural column, receiving the full accent-pipe and icon title treatment, identical to a top-level section.

Title & Icon

Property	Type	Default	Description
`title`	`string`	none	Section heading text. Supports `{FIELDNAME}` tokens to embed live data values.
`titleIcon`	`select`	none	Decorative icon rendered next to the title. Available icons: `check`, `x`, `warning`, `info`, `circlealert`, `star`, `tag`, `package`, `list`, `file-text`, `calendar`, `clock`, `user`, `building`, `shield`.
`accentColor`	`color`	`theme.primary`	Color of the accent pipe and title text in plain (non-boxed) mode.

Title rendering rules

Top-level sections (and sections that are direct columns of a Layout Group): render with a left accent pipe (3pt wide, colored accentColor) and the title icon when set.
Subsections nested inside another section: render as plain bold text only. Font size steps down by 1pt per depth level (minimum 10pt).
When showHeader is enabled (see Header Row below): the title renders inside a filled header row instead, with smart contrast (dark fill produces white text, light fill produces dark text).

Layout

The layout property controls how the section's children are distributed:

Value	Description
`"1"`	Single column - children render one after another (default).
`"2"`	Two columns - children are split at the midpoint and rendered side by side (50/50).

More Than Two Columns

For more than 2 columns, or for non-equal column widths, use a Layout Group instead.

Box Model

Shared by both Section and Layout Group.

Property	Type	Default	Description
`fillColor`	`color`	none	Background fill applied to the content body area.
`padding`	`number`	`8` / `10`	Inner padding (pt) around the content area. Defaults to `10pt` when `showHeader` is on, `8pt` otherwise.
`borderWidth`	`number`	`0` / `0.5`	Outer border thickness (pt). Defaults to `0.5pt` when `showHeader` is on, `0` otherwise.
`borderColor`	`color`	`theme.borderColor`	Outer border color.
`marginTop`	`number`	`8`	Space above the section block (pt).
`marginBottom`	`number`	`0`	Space below the section block (pt).

Header Row (Boxed Mode)

When any box model property is set (showHeader, fillColor, borderWidth, or headerFillColor), the section switches from plain mode to boxed table mode. In boxed mode the title renders inside a dedicated colored header row.

Property	Type	Default	Description
`showHeader`	`toggle`	`false`	Master switch. When on, enables the colored header row, a `0.5pt` border, and `10pt` body padding automatically.
`headerFillColor`	`color`	`theme.primary` when `showHeader` is on	Fill color for the header row. Explicit value overrides the theme default.
`headerBorderBottom`	`number`	`0.5`	Width of the separator line between the header row and the body (pt). Set to `0` to remove.

Smart contrast: The header text color is automatically computed. Dark fills produce white text, light fills produce dark text. titleIcon and sequential section numbers work in both modes.

Table of Contents Integration

Sections can participate in the document TOC when TOC is enabled at the template level.

Property	Type	Default	Description
`tocLabel`	`string`	section `title`	Override the label displayed in the TOC for this section.
`excludeFromTOC`	`toggle`	`false`	Exclude this section from the TOC even when the title matches.

Only top-level sections (depth 0) receive sequential ordinal numbers in headings and the TOC.

Pagination

Property	Path	Description
`Break Before`	`pagination.breakBefore`	`never` / `always` / `whenOverflow` - insert a page break before this section.
`Break After`	`pagination.breakAfter`	`never` / `always` - insert a page break after this section.
`Keep Together`	`pagination.keepTogether`	Prevent the section from splitting across pages. The document engine pushes it entirely to the next page if it would overflow.

Conditional Visibility

Property	Path	Description
`Visible When`	`expressions.visibleWhen`	Expression evaluated at render time. The section is omitted from the PDF when the expression is falsy.

Tip

Trailing Spacer / Separator nodes that immediately precede a hidden section are automatically hidden too, preventing orphaned divider lines.

Nesting Rules

A Section may contain any number of child controls: fields, text nodes, tables, layout groups, spacers, and other sections.
A Section nested inside another section is a subsection. It receives a left indent of 14pt x depth and a reduced font size title.
A Section used as a column container inside a Layout Group is exempt from the indent rule - it renders flush with the column boundary.

Examples

Plain section (theme-driven)

Omit color properties to inherit the active theme automatically.

{
  "type": "section",
  "props": {
    "title": "Order Details",
    "titleIcon": "package",
    "layout": "1"
  }
}

Two-column section

{
  "type": "section",
  "props": {
    "title": "Shipping & Billing",
    "titleIcon": "building",
    "layout": "2"
  }
}

Boxed section with header row

showHeader: true enables the colored header row. Colors default to theme.primary / theme.textOnPrimary and can be overridden with hex values.

{
  "type": "section",
  "props": {
    "title": "Line Items",
    "titleIcon": "list",
    "showHeader": true,
    "headerFillColor": "theme.primary",
    "headerBorderBottom": 0.5,
    "padding": 10,
    "borderWidth": 0.5,
    "borderColor": "theme.borderColor",
    "marginTop": 12,
    "marginBottom": 8
  }
}

Boxed section with custom fill

{
  "type": "section",
  "props": {
    "title": "Notes",
    "titleIcon": "file-text",
    "showHeader": true,
    "headerFillColor": "#1E3A5F",
    "fillColor": "#F8FAFC",
    "padding": 10,
    "borderWidth": 0.5,
    "borderColor": "#CBD5E1",
    "marginTop": 8
  }
}

Subsection (nested inside another section)

Nested sections automatically receive a depth-based indent and a reduced font-size title - no extra config needed.

{
  "type": "section",
  "props": {
    "title": "Billing Address"
  }
}

Section with conditional visibility

{
  "type": "section",
  "props": {
    "title": "Discount Details",
    "titleIcon": "tag"
  },
  "expressions": {
    "visibleWhen": "discountAmount > 0"
  }
}

Section with TOC integration

{
  "type": "section",
  "props": {
    "title": "Terms & Conditions",
    "titleIcon": "shield"
  },
  "settings": {
    "tocLabel": "Terms",
    "excludeFromTOC": false
  },
  "pagination": {
    "breakBefore": "always"
  }
}

Section

On this page