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 | array	"A4"	Named page size, or a custom [width, height] — unit strings ("4in", "152mm", "10cm", "288pt") or bare numbers in points
orientation	string	"portrait"	Page orientation
margins	array	[36, 36, 36, 36]	[top, right, bottom, left] — numbers in points or unit strings ("0.5in", "12.7mm")
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

Label & tag formats

Standard thermal-label stock sizes, named width-first the way the stock is sold:

Size	Dimensions (in)	Typical use
LABEL-4X6	4 x 6	Shipping label, pallet plate
LABEL-4X4	4 x 4	Carton label
LABEL-4X2	4 x 2	Address label
LABEL-3X2	3 x 2	Bin / product tag
LABEL-2X1	2 x 1	Barcode sticker

{
  "document": {
    "pageSetup": {
      "size": "LABEL-4X6",
      "margins": [12, 12, 12, 12]
    },
    "content": [
      { "p": "4 × 6 inch thermal shipping label." }
    ]
  }
}

Omit size to fall back to the engine default (A4).

Custom page sizes

When no named size fits — tickets, badges, wide receipts, oversized placards — set size to a two-element [width, height] array. Each dimension is a unit string in the measure you already think in — "in", "mm", "cm", or "pt":

{
  "document": {
    "pageSetup": {
      "size": ["3.5in", "5.5in"],
      "margins": [12, 12, 12, 12]
    },
    "content": [
      { "p": "3.5 × 5.5 inch event badge." }
    ]
  }
}

["90mm", "140mm"] and ["9cm", "14cm"] work the same way. A bare number is read as points (1 point = 1/72 inch, so 72 pt = 1 inch = 25.4 mm) — the unit the rest of the document model (margins, font sizes) uses.

Each dimension must be between 0.25 and 200 inches (18 to 14,400 points). orientation applies to custom sizes the same way it does to named ones — landscape swaps the two dimensions. Custom sizes work at the document root and in per-section overrides alike.

note

Microsoft Word caps page dimensions at 22 inches (1,584 points). Larger custom pages render fine in PDF, but open oversized in Word from DOCX output.

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 a four-element array:

[top, right, bottom, left]

Each entry is a bare number in points (1 point = 1/72 inch) or a unit string in "in", "mm", "cm", or "pt" — mix freely:

"margins": ["0.75in", "12.7mm", "0.75in", "12.7mm"]

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 color. 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.