Rendering options

The full list of fields for the HTML, URL and Markdown routes (and, except the paper options, for screenshots). All of them are optional.

These routes render with Chromium, the open-source core of Google Chrome, so a page comes out the way Chrome would print it. Everything below is a form field of the request.

Paper and layout

Field	Type	Default	What it does
`paperWidth, paperHeight`	size	`8.5 × 11`	Paper size. Plain numbers are inches; units `in`, `mm`, `cm`, `pt` (1/72 in), `px` (1/96 in) and `pc` (1/6 in) work too. The default is US Letter; A4 is `210mm` × `297mm`.
`marginTop, marginBottom, marginLeft, marginRight`	size	`0.39`	Margins on each side (about 1 cm), in the same units.
`preferCssPageSize`	boolean	`false`	Take the paper size from the page’s CSS `@page { size: ... }` rule.
`landscape`	boolean	`false`	Landscape instead of portrait.
`scale`	number	`1.0`	Zoom the page content, for example `0.8` to fit more on each page.
`singlePage`	boolean	`false`	Put the whole page on one tall sheet instead of breaking it into pages.
`nativePageRanges`	string	–	Only these pages, for example `1-3` or `1,4,6-8`. A range past the last page is an error (400).
`printBackground`	boolean	`false`	Include background colours and images.
`omitBackground`	boolean	`false`	Leave the default white background out, so pages without their own background are transparent. Needs `printBackground=true`.
`generateDocumentOutline`	boolean	`false`	Make PDF bookmarks from the page’s headings (`h1` to `h6`). Turns on `generateTaggedPdf` too.
`generateTaggedPdf`	boolean	`false`	Add the structure tags that screen readers use (an accessible PDF).

Header and footer

Field	Type	Default	What it does
`header.html`	file	–	A complete HTML document drawn at the top of every page, inside the top margin.
`footer.html`	file	–	The same at the bottom, inside the bottom margin.

Add two more files to the request, named exactly header.html and footer.html (you can use either alone). The browser draws them in the top and bottom margin of every page, so make those margins big enough, for example marginTop=1in and marginBottom=0.8in.

They live in a world of their own:

Each is a complete HTML document with its own <style>. The CSS of index.html does not reach it.
No scripts run, and nothing is loaded: no stylesheet links, web fonts or image URLs. Inline images as data: URLs and fonts as system fonts.
The default font size is tiny; set one, for example font-size: 10px on body.
Backgrounds need -webkit-print-color-adjust: exact.

The browser fills elements with these classes on each page:

Class	Becomes
`pageNumber`	the number of this page
`totalPages`	the number of pages
`date`	the print date
`title`	the `<title>` of `index.html`
`url`	the address of the page (for the URL route)

<!doctype html>
<html>
  <head>
    <style>
      body { margin: 0 15mm; width: 100%; font: 9px sans-serif; color: #555;
             display: flex; justify-content: space-between; }
    </style>
  </head>
  <body>
    <span class="title"></span>
    <span>Page <span class="pageNumber"></span> / <span class="totalPages"></span></span>
  </body>
</html>

Waiting

The browser prints when the page has loaded. Pages that draw charts or fetch data with JavaScript may need more time. Tell the API what to wait for:

Field	Type	Default	What it does
`waitDelay`	duration	–	A fixed pause after loading, for example `750ms` or `3s`. Simple, but either too long or too short; prefer the next two.
`waitForSelector`	string	–	Print once an element matching this CSS selector is on the page, for example `#chart.ready`.
`waitForExpression`	string	–	Print once this JavaScript expression is true, for example `window.reportDone === true`. An expression that throws or gives `undefined` is an error (400).
`waitWindowStatus`	string	–	Print once `window.status` has this value, for example `ready`. The page sets it with `window.status = 'ready'`.
`skipNetworkIdleEvent`	boolean	`true`	Set to `false` to also wait until the page has made no network requests for half a second. Slower, but catches late images and data.
`skipNetworkAlmostIdleEvent`	boolean	`true`	Set to `false` to wait until at most two requests are still open. A middle way between the default and `skipNetworkIdleEvent=false`.

Waiting counts against the 60-second limit. A condition that never comes true ends in a timeout, so make sure your page also gets there when its data fails to load.

// In your page: draw, then signal that printing may start.
await drawCharts();
window.status = "ready";             // for waitWindowStatus=ready
document.body.dataset.ready = "1";   // for waitForSelector=body[data-ready]

Browser and requests

Field	Type	Default	What it does
`emulatedMediaType`	string	`print`	`screen` applies the CSS for screens instead of `@media print`.
`emulatedMediaFeatures`	JSON object	–	CSS media features to pretend, for example `{"prefers-color-scheme": "dark", "prefers-reduced-motion": "reduce"}`.
`userAgent`	string	–	The `User-Agent` the browser sends.
`extraHttpHeaders`	JSON object	–	Headers the browser adds to its requests, for example `{"X-Report-Token": "abc"}`. Up to 64. Add `;scope=<regular expression>` to a value to send it only to matching URLs: `"abc;scope=https://reports\\.example\\.com/.*"`.
`cookies`	JSON array	–	Cookies set before the page loads. Each needs `name`, `value` and `domain`; `path`, `secure`, `httpOnly` and `sameSite` (`Strict`, `Lax`, `None`) are optional.

Cookies and headers are for this one request; nothing is kept between requests. Do not send long-lived secrets: use tokens that expire within minutes.

Failing on purpose

By default the browser prints what it gets, even when some images are missing. These checks turn problems into a 409 answer that lists them, so a broken PDF never reaches your customer:

Field	Type	Default	What it does
`failOnHttpStatusCodes`	JSON array	`[499, 599]`	Fail with 409 when the page itself answers with one of these statuses. A number ending in 99 stands for its whole hundred: `499` is 400 to 499. `[]` prints whatever comes back.
`failOnResourceHttpStatusCodes`	JSON array	–	Fail with 409 when an image, stylesheet, script or other resource of the page answers with one of these statuses, for example `[404, 599]`.
`ignoreResourceHttpStatusDomains`	JSON array	–	Domains whose resources the check above leaves out, for example `["analytics.example.com"]`. Subdomains are included.
`failOnResourceLoadingFailed`	boolean	`false`	Fail with 409 when a resource cannot be loaded at all (a DNS error, a refused connection, a blocked address).
`failOnConsoleExceptions`	boolean	`false`	Fail with 409 when the page throws an uncaught JavaScript exception. The message lists them.

Combining with PDF options

The HTML, URL and Markdown routes also take the options on conversion routes: PDF/A and PDF/UA, metadata, passwords, watermarks and stamps, rotation, splitting, image compression, attachments and Factur-X. They run on the PDF after the browser has printed it, still in one request.