Set paper size, margins, and background printing in the options passed to page.pdf(). Puppeteer defaults to Letter paper and print CSS; margins are not added by the margin option unless you set them, and background graphics are omitted unless you enable printBackground. If your page defines its own paper size with CSS @page, set preferCSSPageSize: true to give that size priority.
Choose how Puppeteer determines PDF page size
Puppeteer offers three related controls: a named paper format, custom width and height, or a CSS @page size. Use one deliberately: when format is set, it takes precedence over width and height. The default format is Letter. By default, preferCSSPageSize is false, so CSS page dimensions are scaled to fit the API-selected paper size.
| Approach | Option | Behavior |
|---|---|---|
| Named paper | format |
Uses a documented paper format; defaults to Letter. |
| Custom dimensions | width and height |
Sets paper dimensions directly. Use explicit units such as in or mm so the intended size is clear. |
| CSS page dimensions | preferCSSPageSize: true |
Gives CSS @page sizing priority over the API paper size. The default is false, which scales CSS page dimensions to fit the selected paper. |
Common named formats
Puppeteer’s documented formats include these dimensions:
| Format | Dimensions |
|---|---|
| Letter | 8.5 × 11 in (21.59 × 27.94 cm) |
| Legal | 8.5 × 14 in (21.59 × 35.56 cm) |
| Tabloid | 11 × 17 in (27.94 × 43.18 cm) |
| Ledger | 17 × 11 in (43.18 × 27.94 cm) |
| A4 | 8.2677 × 11.6929 in (21 × 29.7 cm) |
| A3 | 11.6929 × 16.5354 in (29.7 × 42 cm) |
| A5 | 5.8268 × 8.2677 in (14.8 × 21 cm) |
These are the dimensions listed for Puppeteer’s paper formats, not independent measurements of generated PDF output. See the PaperFormat reference for the documented formats.
#1 Best Overall
- 1 ream (500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Set margins and orientation
Pass a margin object with any combination of top, right, bottom, and left. Each value accepts a string or number. The margin object is optional; if you omit it, the API option does not set margins.
Set landscape: true for landscape orientation. Its default is false. This changes orientation, not the choice between a named format, custom dimensions, or CSS page sizing.
Rank #2
- HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America. Each ream is wrapped in a polyurethane coated paper wrapper to protect the cut sheets from moisture damage
- Sheet size – 8.5 x 11; Thickness – 20 pounds; Brightness – 92 bright white
- HP Copy&Print20 20 pounds printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design)
- All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment; 100% satisfaction guaranteed; ColorLok technology provides more vivid colors, bolder blacks and faster drying
- Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office; HP Copy&Print20 print and copy paper prevents yellowing over time to ensure a long-lasting appearance for added archival quality
Control printed backgrounds and colors
Background graphics are excluded by default. Set printBackground: true to include them. This is separate from omitBackground: true, which hides the default white background and allows PDF transparency. If the output needs both printed graphics and a transparent page, check the resulting PDF in your target viewer rather than assuming the options serve the same purpose.
Print rendering modifies colors by default. Puppeteer’s documentation identifies CSS -webkit-print-color-adjust as the way to force exact colors:
Rank #3
- 3 ream case (1,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
@media print {
body {
-webkit-print-color-adjust: exact;
}
}Use this only where preserving the authored colors matters; print styling can also be tailored independently with CSS.
Use print CSS or screen CSS
page.pdf() renders with the print CSS media type. If the PDF should use styles intended for an on-screen page, call page.emulateMediaType('screen') before generating it. CSS media selection and paper sizing solve different problems: media type chooses which styles apply, while format, dimensions, and @page determine the sheet size.
Rank #4
- 5 ream case (2,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Complete example
This Node.js example selects A4, adds independent margins, prints backgrounds, and enables CSS page-size priority. Remove preferCSSPageSize if you want the selected format to control paper size even when the page declares an @page size.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.pdf({
path: 'page.pdf',
format: 'A4',
preferCSSPageSize: true,
landscape: false,
margin: {
top: '12mm',
right: '12mm',
bottom: '12mm',
left: '12mm',
},
printBackground: true,
});
} finally {
await browser.close();
}
})();For fixed custom paper dimensions instead, use width and height with explicit units and omit format; otherwise the named format takes priority. The PDFOptions reference documents the available options.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- 8 ream case (4,000 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Troubleshoot unexpected PDF output
- The PDF is the wrong paper size: Check whether
formatis overriding yourwidthandheight. If the page’s CSS@pagedimensions should win, enablepreferCSSPageSize. - Background colors or graphics are missing: Set
printBackground: true. If the colors still differ, consider-webkit-print-color-adjust: exactin print CSS. - The page is unexpectedly white or transparency is needed: Check
omitBackground; it hides the default white background and permits transparency. - The layout differs from the browser view: PDF generation uses print CSS by default. Call
page.emulateMediaType('screen')beforepage.pdf()if screen styles are intended. - Margins do not match the intended layout: Set each needed side explicitly in
margin; the API does not set a margin object by default.
WebDriver BiDi compatibility
If your Puppeteer runtime uses WebDriver BiDi, do not assume every general PDFOptions setting is supported there. Puppeteer’s BiDi support page lists format, height, landscape, margin, pageRanges, printBackground, scale, and width for Page.pdf(); it does not list preferCSSPageSize or omitBackground. Check the WebDriver BiDi support guide for the mode-specific option list.
Or skip the browser setup
If you need a screenshot or PDF from a URL rather than control over Puppeteer’s browser internals, ScreenshotNeo offers a one-request API. For example, save a page screenshot as WebP with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; and an MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Frequently Asked Questions
Can Puppeteer use CSS @page size instead of format?
Yes. Set preferCSSPageSize: true so CSS @page dimensions take priority.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsDoes Puppeteer print page backgrounds by default?
No. Set printBackground: true to include background graphics.
Can a Puppeteer PDF have a transparent background?
Set omitBackground: true to hide the default white background and allow transparency.
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.
