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:
{"html": "...", "options": {"format": "Letter", "landscape": true, "margins": {"top": "20mm", "bottom": "20mm"}}}
| Option | Values |
|---|---|
format | A4 (default), Letter, Legal, A3, A5 |
landscape | true or false (default) |
margins | top, right, bottom, left as lengths such as 10mm, 1in or 20px; each is 10mm by default |
scale | 0.1 to 2.0 (default 1) |
print_background | true (default) prints background colours and images; false leaves them out |
prefer_css_page_size | true to use the page size from your CSS @page rule |
header_template, footer_template | HTML for a header and footer on every page (see below) |
wait_until | load (default) or networkidle |
javascript | true (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.
"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)andcounter(pages)print0in normal page content. Use them in a margin box, or usefooter_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.
Related
- Files and fonts: send your stylesheets, images and fonts.
- API reference: the complete list of options and their defaults.
Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.