Skip to main content

​
Page properties (converters)

Pass properties to convert() to control the generated PDF:
PropertyTypeDescription
singlePagebooleanRender entire content on one page (default: false)
size{ width, height }Paper size. Numbers = inches; strings support pt, px, in, mm, cm, pc (e.g. "210mm", "297mm" for A4)
margins{ top, bottom, left, right }Margins; same unit rules as size
preferCssPageSizebooleanUse CSS page size when set (default: false)
printBackgroundbooleanInclude background graphics (default: false)
omitBackgroundbooleanTransparent background (default: false)
landscapebooleanLandscape orientation (default: false)
scalenumberPage scale (default: 1.0)
nativePageRanges{ from, to }Page range to print
Example with units: 
await urlConverter.convert({
  url: "https://example.com/",
  properties: {
    size: { width: "210mm", height: "297mm" },
    margins: { top: "1cm", bottom: "1cm", left: "2cm", right: "2cm" },
  },
});

​
Standard paper sizes

Common sizes (width × height) you can use in properties.size:
FormatDimensions (in)Example size
A64.13 × 5.83{ width: 4.13, height: 5.83 }
A55.83 × 8.27{ width: 5.83, height: 8.27 }
A48.27 × 11.7{ width: "210mm", height: "297mm" }
Letter8.5 × 11 (default){ width: 8.5, height: 11 }
Legal8.5 × 14{ width: 8.5, height: 14 }
A311.7 × 16.54{ width: "297mm", height: "420mm" }

​
Single page

When singlePage is true, Chromium fits the entire content on one long page and overrides paper height and native page ranges. Chromium uses print media by default. The PDF can look different from the browser (e.g. backgrounds omitted). Use printBackground: true to include background graphics, or set emulatedMediaType: "screen" (in conversion options) to use screen media. You can target print in CSS with @media print; use preferCssPageSize: true so Chromium respects @page size and margins.

​
Background logic

The resulting background depends on printBackground, omitBackground, and whether your document has a background:
printBackgroundomitBackgroundDocument has background?Result
falseanyanyNo background
trueanyYesUses HTML/CSS background
truetrueNoTransparent
truefalseNoWhite (default)

​
Rendering and wait

Chromium captures the current DOM. If the page uses JavaScript to render content (e.g. SPAs, charts), use wait options so conversion runs when content is ready. Prefer waitForExpression or waitForSelector over waitDelay: they are more reliable. Use waitDelay only as a fallback when you cannot change the page; it is less reliable if load time varies.

​
Conversion options (converters)

In addition to properties, convert() accepts:
  • Wait: waitDelay (e.g. "5s"), waitForSelector, waitForExpression — see Rendering and wait
  • Header/footer: header, footer — path, Buffer, or ReadStream (see below)
  • HTTP: extraHttpHeaders, cookies, failOnHttpStatusCodes, failOnResourceHttpStatusCodes, ignoreResourceHttpStatusDomains, failOnResourceLoadingFailed, skipNetworkIdleEvent (see below)
  • Behavior: failOnConsoleExceptions, failOnResourceLoadingFailed, skipNetworkIdleEvent
  • PDF: pdfUA (accessibility), metadata, userPassword, ownerPassword, embeds
  • Split: split — { mode: "pages" | "intervals", span, unify?, flatten? }
See Reference — types for full type definitions. Headers and footers are rendered in an isolated context: your main page’s CSS does not apply, JavaScript does not run, and external requests (images, fonts) are not allowed. Provide complete HTML documents. Chromium injects dynamic values into elements with these class names: pageNumber, totalPages, date, title, url. Use base64-encoded images inline (e.g. <img src="data:image/png;base64,...">). Add -webkit-print-color-adjust: exact; in your header/footer CSS if you need background or text colors to print.

​
HTTP and networking

  • extraHttpHeaders — Object of header name → value; sent with every request (main page and resources). You can scope a header to certain URLs by appending ;scope=<regex> to the value (the token is stripped before sending).
  • cookies — Array of { name, value, domain } (and optional path, secure, httpOnly, sameSite) for authentication or session state.
  • failOnHttpStatusCodes — Array of status codes (or ranges via X99 notation, e.g. 499 = 400–499). If the main page returns a matching code, Gotenberg returns 409 Conflict. Default is [499, 599].
  • failOnResourceHttpStatusCodes — Same for subresources (images, CSS, scripts). Use ignoreResourceHttpStatusDomains to exclude hostnames from this check (e.g. analytics).
  • failOnResourceLoadingFailed — If true, conversion fails with 400 when any resource fails to load (e.g. 404 image); by default the PDF is still generated with missing assets.
  • skipNetworkIdleEvent — If true, Chromium does not wait for the network to be idle before converting (default false).

​
Screenshot options (capture)

Pass properties to capture() for image output:
PropertyTypeDescription
format"png" | "jpeg" | "webp"Image format
qualitynumber (0–100)JPEG compression quality
omitBackgroundbooleanTransparent background
widthnumberViewport width in pixels (default: 800)
heightnumberViewport height in pixels (default: 600)
clipbooleanClip to viewport (default: false)
Other capture() options mirror the conversion options where applicable (e.g. waitDelay, waitForSelector, extraHttpHeaders, optimizeForSpeed). See Reference — screenshots.