Docs / Guides / PDF page size, margins and page breaks

Docs menu · PDF page size, margins and page breaks

Guides

PDF page size, margins and page breaks

Control the page size, margins, headers and footers, and read the tips that help real documents come out right.

The options object

Add options to a request to control the page:

JSON
{"html": "...", "options": {"format": "Letter", "landscape": true, "margins": {"top": "20mm", "bottom": "20mm"}}}
OptionValues
formatA4 (default), Letter, Legal, A3, A5
landscapetrue or false (default)
marginstop, right, bottom, left as lengths such as 10mm, 1in or 20px; each is 10mm by default
scale0.1 to 2.0 (default 1)
print_backgroundtrue (default) prints background colours and images; false leaves them out
prefer_css_page_sizetrue to use the page size from your CSS @page rule
header_template, footer_templateHTML for a header and footer on every page (see below)
wait_untilload (default) or networkidle
javascripttrue (default) runs scripts in your page; false turns them off

If a value is not valid, you get 400 INVALID_OPTIONS with a message that names the option and what it accepts.

Headers and footers with page numbers

The templates are small HTML snippets. Give them a font size (the default is tiny) and leave room for them with the margins. These placeholders are filled in on every page: pageNumber, totalPages, date and title.

JSON
"options": {
  "margins": {"top": "25mm", "bottom": "20mm"},
  "header_template": "<div style='font-size:9px; width:100%; text-align:center; font-family:sans-serif'>ACME Ltd. Invoice</div>",
  "footer_template": "<div style='font-size:9px; width:100%; text-align:center; font-family:sans-serif'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"
}

Page breaks

Content flows onto as many pages as it needs (up to 20). To start a new page, use CSS: <section style="break-before: page">. To keep something in one piece, such as a table row, use break-inside: avoid.

Page size in CSS

If your stylesheet already has an @page { size: ...; margin: ... } rule, set "prefer_css_page_size": true and Stolid PDF follows it.

Page numbers and footers in CSS

Stolid PDF renders with Chromium. Test the print CSS your templates depend on: a few features behave differently from other layout engines and produce no warning. It supports @page margin boxes such as @bottom-right { content: "Page " counter(page) " of " counter(pages); }, and the :first, :left and :right page selectors. A few print CSS features behave differently, and the render report does not warn about them:

  • counter(page) and counter(pages) print 0 in normal page content. Use them in a margin box, or use footer_template.
  • @page :nth(3) is ignored, so its margin boxes do not appear.
  • position: running() leaves the element where it is in the page, once, instead of repeating it on each page.

Page images (coming soon)

Page images: coming soon

Optional images of the rendered pages, so an agent can look at the result, are not available yet. Today a render returns the PDF and the render report.

Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.