Use Puppeteer’s page.pdf() options to set paper size, orientation, margins, and whether CSS background graphics appear in the PDF. For example, choose format: 'A4', set each margin in margin, and enable backgrounds with printBackground: true. Puppeteer generates PDFs using print CSS by default; if your stylesheet’s @page size should control the paper, also set preferCSSPageSize: true.
Set paper size, margins, and background graphics
Pass a PDFOptions object to page.pdf(). This example uses A4 paper, portrait orientation, explicit margins, and printed CSS backgrounds:
await page.pdf({
format: 'A4',
landscape: false,
margin: {
top: '20mm',
right: '15mm',
bottom: '20mm',
left: '15mm',
},
printBackground: true,
});Use strings with explicit units for margins so the intended measurements are clear. You can use standard paper names such as A4 or Letter, or set custom width and height values. If you omit margin, Puppeteer sets no margins.
Choose a standard paper size or custom dimensions
format selects a standard paper size. Puppeteer documents Letter as 8.5 × 11 inches (21.59 × 27.94 cm) and A4 as 210 × 297 mm (8.2677 × 11.6929 inches). Choose the size required by the destination or document standard; they are not interchangeable dimensions. See the Puppeteer PaperFormat reference for the supported format names.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
If you specify format together with width and height, format takes priority. Use width and height when you need a custom paper size instead of a named standard.
Set orientation
Set landscape: true for landscape output. The documented default is false, so the PDF is portrait unless you change it.
Set all four margins explicitly
The margin object accepts top, right, bottom, and left values. Its values may be strings or numbers; explicit unit strings such as '15mm' make the intended measurement easier to read and maintain. Do not rely on a browser or stylesheet margin when you need a predictable PDF margin: specify the four sides in the PDF options.
Print CSS background graphics
Set printBackground: true to include CSS background graphics. It is false by default. The separate omitBackground option controls whether the default white page background is hidden, which permits transparent PDFs; it does not enable CSS background graphics. For colored page backgrounds, patterns, or other CSS background artwork, use printBackground.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDecide whether Puppeteer options or CSS controls page size
Puppeteer uses the print CSS media type when it generates a PDF. If the page defines paper dimensions with CSS @page, set preferCSSPageSize: true to give that CSS size priority over format, width, and height. This option defaults to false; in that case, Puppeteer scales the content to fit the paper size supplied in its options.
await page.pdf({
preferCSSPageSize: true,
printBackground: true,
margin: {
top: '20mm',
right: '15mm',
bottom: '20mm',
left: '15mm',
},
});Use that approach when the document’s own print stylesheet defines the paper dimensions. For example, a stylesheet can declare:
@page {
size: A4;
}In this example, preferCSSPageSize: true makes the CSS @page size take precedence. If you instead want the Puppeteer format setting to determine the output size, leave preferCSSPageSize false and set format explicitly. Avoid assuming that a CSS size and a Puppeteer format agree unless you have deliberately set them to the same paper dimensions.
Use screen styling only when that is the intended output
PDF generation uses print media styling by default, so rules in @media print apply. If the PDF should reflect screen styles instead, switch media type before generating it:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →await page.emulateMediaType('screen');
await page.pdf({
format: 'A4',
printBackground: true,
});Changing media type affects which CSS rules are active; it does not replace paper-size, margin, or background options. The Puppeteer Page.pdf() reference describes PDF generation and print media behavior.
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
Control print color when exact colors matter
Print rendering may adjust colors for printing. For output where CSS colors should be preserved, Puppeteer points to the CSS property -webkit-print-color-adjust. Apply it in the print styles for the relevant elements, then enable printBackground if those colors are used as backgrounds. These settings address different things: color adjustment affects print color treatment, while printBackground determines whether CSS background graphics are included.
Complete Node.js example
The following CommonJS script opens a page and writes an A4 PDF with explicit margins and backgrounds. Install Puppeteer in your project with npm install puppeteer, save this as make-pdf.cjs, and run node make-pdf.cjs https://example.com.
const puppeteer = require('puppeteer');
async function main() {
const url = process.argv[2];
if (!url) {
throw new Error('Usage: node make-pdf.cjs <url>');
}
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto(url, { waitUntil: 'networkidle0' });
await page.pdf({
path: 'page.pdf',
format: 'A4',
landscape: false,
margin: {
top: '20mm',
right: '15mm',
bottom: '20mm',
left: '15mm',
},
printBackground: true,
});
} finally {
await browser.close();
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});This example waits for network activity to settle before capture. Some sites keep network connections open, so networkidle0 may not be appropriate for every page; choose a navigation or page-readiness condition that matches the site you are capturing. The example relies on Puppeteer’s default print media behavior. To use screen styles, call page.emulateMediaType('screen') before page.pdf(). To use CSS-defined paper dimensions, add the relevant @page rule and set preferCSSPageSize: true.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
Version-sensitive defaults to check
The official Puppeteer PDFOptions reference showed version 25.12.0 when consulted on October 3, 2026. For that documented version, the defaults include format: 'letter', landscape: false, printBackground: false, preferCSSPageSize: false, scale: 1, waitForFonts: true, and a 30,000 ms PDF timeout. The same reference says that an omitted margin sets no margins. Defaults and API availability can change, so check the documentation for the Puppeteer version pinned in your project.
Troubleshoot common PDF output problems
The PDF uses the wrong paper dimensions
- Check whether you set both
formatandwidth/height;formattakes precedence over those dimensions. - Check for a CSS
@pagesize. If it should win, setpreferCSSPageSize: true; otherwise, set the intended Puppeteer paper option and leave CSS sizing preference off. - Confirm that the desired standard is actually A4, Letter, or another supported size rather than assuming those formats match.
Background colors or images are missing
- Set
printBackground: true; its default is false. - Do not use
omitBackgroundas a substitute. That option concerns the default white page background and transparency, not printing CSS backgrounds. - Check whether the relevant CSS is inside print or screen media rules. Puppeteer uses print media unless you explicitly emulate screen media.
Margins are missing or inconsistent
- Set all four sides under
margininstead of omitting the option. - Use explicit units in string values, such as
'20mm', so the measurement is unambiguous. - Check whether the page’s CSS
@pagerules are also setting print layout, especially whenpreferCSSPageSizeis enabled.
Colors look different from the browser page
PDF generation uses print styling, where print color treatment may differ from screen rendering. Check the page’s print CSS and use -webkit-print-color-adjust where preserving CSS colors is important. Also ensure backgrounds are enabled if the colors are backgrounds.
The PDF operation times out
The version 25.12.0 API reference documents a 30,000 ms PDF timeout. If generation exceeds the timeout, inspect whether the page is still loading resources or whether its print layout is expensive, then consult the options for your pinned Puppeteer version before changing timeout behavior.
Or skip the browser setup
If your task is to request a page capture without managing Puppeteer, ScreenshotNeo provides a screenshot API and an MCP server for developers. A GET request can return a screenshot or PDF; its screenshot controls are not a replacement for Puppeteer’s CSS print-layout configuration when you specifically need to tune @page rules or PDF margins.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The cURL example below requests a WebP capture of Stripe. See the ScreenshotNeo documentation for API options and PDF usage.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie and consent banners are accepted like a visitor, and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; responses identify the page verdict and billing status in headers.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
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.
