Page Setup

The pageSetup object controls the physical layout of every page in your PDF. All properties are optional and fall back to sensible defaults when omitted.

Properties

Property	Type	Default	Description
size	string	"A4"	Named page size
orientation	string	"portrait"	Page orientation
margins	number[]	[36, 36, 36, 36]	Margins in points: [top, right, bottom, left]
backgroundColor	string | string[]	—	Page background. Single hex string for one color, array for per-page banding (cycles when fewer entries than pages).
borderTop	string	—	Top page border — CSS shorthand "<width> <style> <color>" (e.g. "1pt solid #000", "none").
borderRight	string	—	Right page border (CSS shorthand).
borderBottom	string	—	Bottom page border (CSS shorthand).
borderLeft	string	—	Left page border (CSS shorthand).

Page sizes

DocPayload supports all standard ISO and North American page sizes:

ISO A series

Size	Dimensions (mm)
A0	841 x 1189
A1	594 x 841
A2	420 x 594
A3	297 x 420
A4	210 x 297
A5	148 x 210
A6	105 x 148
A7	74 x 105
A8	52 x 74
A9	37 x 52
A10	26 x 37

ISO B series

Size	Dimensions (mm)
B1	707 x 1000
B2	500 x 707
B3	353 x 500
B4	250 x 353
B5	176 x 250
B6	125 x 176
B7	88 x 125
B8	62 x 88
B9	44 x 62
B10	31 x 44

North American sizes

Size	Dimensions (in)
LETTER	8.5 x 11
LEGAL	8.5 x 14
TABLOID	11 x 17
LEDGER	17 x 11
EXECUTIVE	7.25 x 10.5

Default

Use DEFAULT to inherit the system default, which is equivalent to A4.

Orientation

Value	Description
portrait	Taller than wide (default)
landscape	Wider than tall

When landscape is set, the page dimensions are swapped. For example, A4 landscape produces a 297 x 210 mm page.

Margins

Margins are specified as a four-element array in points (1 point = 1/72 inch):

[top, right, bottom, left]

For reference:

• 72 points = 1 inch = 25.4 mm
• 50 points is approximately 17.6 mm or 0.69 inches

Examples

A4 portrait with default margins

{
  "document": {
    "pageSetup": {
      "size": "A4",
      "orientation": "portrait",
      "margins": [50, 40, 50, 40]
    },
    "content": [
      { "p": "Standard A4 document." }
    ]
  }
}

US Letter landscape with wide margins

{
  "document": {
    "pageSetup": {
      "size": "LETTER",
      "orientation": "landscape",
      "margins": [72, 72, 72, 72]
    },
    "content": [
      { "p": "Landscape letter with 1-inch margins on all sides." }
    ]
  }
}

Legal portrait with narrow side margins

{
  "document": {
    "pageSetup": {
      "size": "LEGAL",
      "orientation": "portrait",
      "margins": [60, 30, 60, 30]
    },
    "content": [
      { "p": "Legal-size document with narrow side margins for maximum content width." }
    ]
  }
}

Tabloid for large-format reports

{
  "document": {
    "pageSetup": {
      "size": "TABLOID",
      "orientation": "portrait",
      "margins": [50, 50, 50, 50]
    },
    "content": [
      { "p": "Tabloid-size document for large charts and diagrams." }
    ]
  }
}

Page background colors

Apply different background colors to successive pages. Colors cycle if there are more pages than entries.

{
  "document": {
    "pageSetup": {
      "size": "A4",
      "margins": [
        50,
        40,
        50,
        40
      ],
      "backgroundColor": [
        "#FAFAFA",
        "#F0F4FF"
      ]
    },
    "content": [
      {
        "p": "Page 1 has a light gray background."
      },
      {
        "break": "page"
      },
      {
        "p": "Page 2 has a light blue background."
      },
      {
        "break": "page"
      },
      {
        "p": "Page 3 cycles back to light gray."
      }
    ]
  }
}

note

backgroundColor currently renders on top of content in some configurations. Use light, subtle colors and test your output to ensure readability.

Page borders

Add border rules to every page. Each side is its own property — borderTop, borderRight, borderBottom, borderLeft — using the CSS shorthand "<width> <style> <color>". Components are independently optional and can appear in any order; "none" removes the side. Sides are independent: setting borderTop doesn't reset the others.

{
  "document": {
    "pageSetup": {
      "size": "A4",
      "margins": [50, 40, 50, 40],
      "borderTop": "0.5pt solid #CCCCCC",
      "borderBottom": "0.5pt solid #CCCCCC"
    },
    "content": [
      { "p": "This document has thin gray rules at the top and bottom of every page." }
    ]
  }
}

Combine all four sides for a full page frame:

"pageSetup": {
  "borderTop": "1pt solid #1A1A2E",
  "borderRight": "1pt solid #1A1A2E",
  "borderBottom": "1pt solid #1A1A2E",
  "borderLeft": "1pt solid #1A1A2E"
}

Per-section overrides

The pageSetup at the document root is the default for every page. To change page setup partway through — a landscape appendix, a different page size for an insert, narrower margins for a chapter — partition the document with a section break that carries its own inline pageSetup.

{
  "document": {
    "pageSetup": {
      "size": "LETTER",
      "orientation": "portrait",
      "margins": [50, 50, 50, 50]
    },
    "content": [
      { "h1": "Main body" },
      { "p": "Renders with the document-root pageSetup (LETTER portrait)." },

      { "break": "section",
        "pageSetup": {
          "size": "TABLOID",
          "orientation": "landscape",
          "margins": [30, 30, 30, 30],
          "backgroundColor": "#FAFAFA"
        }
      },

      { "h1": "Appendix" },
      { "p": "Renders TABLOID landscape with the appendix pageSetup applied to every page in this section." }
    ]
  }
}

The inline pageSetup on the break accepts every key the document-root pageSetup does — size, orientation, margins, backgroundColor, borderTop/borderRight/borderBottom/borderLeft. Each property is independent: omit a key to inherit it from the document root. The break also accepts inline header / footer for per-section chrome (see Headers & Footers).

pageSetup is for page-level configuration only — it does not accept content-formatting keys like fontSize or fontColor. Those belong in styles and apply to text elements, not pages.

A section break starts a new page when the resolved page setup differs from the previous section's. Sections sharing identical setup may render on the same physical page.