Free tools Windows power users keep installed
One-click scans. No signup required.
Use Puppeteer’s page.pdf() options to set paper size, margins, orientation, and background graphics. The key switches are format (or custom width and height), margin, and printBackground: true. Puppeteer generates PDFs using print CSS by default.
Set paper size, margins, and background graphics
Here is a complete example for an A4 PDF with explicit margins and CSS background graphics included:
As an Amazon Associate I earn from qualifying purchases.
const pdf = await page.pdf({
format: 'A4',
margin: {
top: '20mm',
right: '15mm',
bottom: '20mm',
left: '15mm',
},
printBackground: true,
});page.pdf() returns the generated PDF as a buffer. Save it to a file with Node’s filesystem API if needed:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →const fs = require('node:fs/promises');
await fs.writeFile('page.pdf', pdf);The Puppeteer PDFOptions reference documents these settings and their defaults. Its version 25.12.0 reference lists Letter as the default format; defaults and option behavior can vary by Puppeteer version.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Choose a page size and orientation
Standard formats
Set format to a supported paper name such as 'A4' or 'Letter'. Letter measures 8.5 × 11 inches (21.59 × 27.94 cm); A4 measures 210 × 297 mm (about 8.2677 × 11.6929 inches). Pick the size required by the document’s destination rather than assuming one format fits all.
When format is supplied, it takes priority over width and height. Avoid specifying conflicting values: choose either a standard format or custom dimensions.
Custom dimensions
For a nonstandard sheet, set width and height using explicit CSS units, for example '100mm' and '150mm'. Puppeteer’s documentation allows dimensions as strings or numbers; unit-bearing strings make the intended measurement unambiguous.
Landscape
Use landscape: true to switch the page orientation. The documented default is false. Example: await page.pdf({ format: 'A4', landscape: true }).
Control the four margins
Pass a margin object with any or all of top, right, bottom, and left. The values may be strings or numbers. If the option is omitted, Puppeteer sets no margins. For print layouts, explicit units such as '12mm' or '0.5in' are easier to review and maintain than unitless values.
await page.pdf({
format: 'Letter',
margin: {
top: '0.75in',
right: '0.65in',
bottom: '0.75in',
left: '0.65in',
},
});Include backgrounds and preserve print colors
Background graphics are not printed by default. Set printBackground: true to include CSS background colors and images. This is separate from omitBackground: that option removes the default white page background to allow transparency; it does not enable CSS background printing.
PDF printing may adjust colors for print output. If exact CSS colors matter, Puppeteer’s PDF guidance points to the CSS property -webkit-print-color-adjust. Apply it intentionally in your print stylesheet, for example:
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute@media print {
html {
-webkit-print-color-adjust: exact;
}
}Color adjustment and printBackground solve different problems: the first concerns print color treatment, while the second determines whether CSS backgrounds are included at all.
Decide whether Puppeteer options or CSS controls page size
Puppeteer uses the document’s print media styles when creating a PDF. If your stylesheet defines an @page size and you want that size to take precedence over the API’s format or dimensions, set preferCSSPageSize: true:
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
@page {
size: A4 landscape;
margin: 20mm 15mm;
}await page.pdf({
format: 'Letter',
preferCSSPageSize: true,
printBackground: true,
});With preferCSSPageSize: true, CSS page dimensions win over format, width, and height. In this example, the CSS-defined A4 landscape size wins despite format: 'Letter'. Without the preference, Puppeteer scales content to fit the paper size specified in the PDF options.
If you want screen styles rather than print styles, call await page.emulateMediaType('screen') before page.pdf(). Otherwise, print media is used.
Check the result when layout differs from expectations
- Wrong paper size: Check whether
formatoverrides yourwidthandheight, or whetherpreferCSSPageSizegives an@pagerule priority. - Unexpected whitespace: Set all four
marginvalues explicitly; an omitted margin option means no margins are set by Puppeteer, though print CSS may define page margins. - Missing color blocks or background images: Enable
printBackground: true. Check print styles as well, since PDF generation uses print media by default. - Transparent page needed: Use
omitBackgroundfor the default white page background; do not use it as a substitute forprintBackground. - Colors look different from the browser: Review print CSS and consider
-webkit-print-color-adjustwhere faithful color rendering is required. - Screen-only styling disappeared: Either create appropriate print rules or call
page.emulateMediaType('screen')before generating the PDF.
The option defaults and PDF API are version-sensitive. If your project pins a different Puppeteer release, check its matching API reference rather than assuming the 25.12.0 defaults apply.
Best Value
Or skip the browser setup
If you need a PDF from a URL without managing Puppeteer and a browser instance, ScreenshotNeo provides a screenshot API and PDF capture. Its MCP server also gives AI agents tools for taking screenshots and capturing PDFs. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.pdfSee the ScreenshotNeo documentation for API parameters. The service offers 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for the free plan.
Frequently Asked Questions
Does Puppeteer print CSS backgrounds by default?
No. Set printBackground: true in page.pdf() to include them.
Recommended Free Tools
What is the default PDF paper size in Puppeteer?
The Puppeteer 25.12.0 PDFOptions reference lists Letter as the default. Confirm the documentation for the version your project uses.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
