The short answer: Puppeteer can produce different-looking or differently sized PDFs because two systems control the result: the PDF options passed to page.pdf() and the document’s print CSS, especially @page. By default, Puppeteer uses Letter paper, print media, its own margins and a scale of 1. Set one geometry authority, make paper size, orientation, margins and scale explicit, wait for fonts and application data, and decide deliberately whether CSS or the API wins.
What actually determines a Puppeteer PDF’s dimensions
page.pdf() renders with the print CSS media type, not the screen media type. Its PDF options can set format, explicit width and height, margins, landscape, scale and preferCSSPageSize. The documented default format is letter; the default scale is 1, and the allowed scale range is 0.1 through 2.
CSS can also declare a paper size:
@page { size: A4; }Named sizes such as A4 and letter, absolute sizes such as 4in 6in, and portrait or landscape orientation are valid CSS choices. If the API and CSS disagree, preferCSSPageSize decides which authority wins. Its default is false, so an API-selected paper size is used and a CSS page size is scaled to fit it. Set it to true when the CSS @page size must take priority.
| Control | What it changes | Default or documented range |
|---|---|---|
format |
Standard paper such as Letter or A4 | Letter when omitted |
width, height |
Explicit paper dimensions | Use units such as mm, in or px |
landscape |
Swaps page orientation | Portrait unless enabled |
margin |
Printable content box inside the paper | Set each side explicitly for repeatability |
scale |
Scales rendered content, not the paper box | 1; range 0.1–2 |
preferCSSPageSize |
Chooses CSS @page size over API geometry |
false |
Why the size appears to change
Conflicting size authorities
A format, width or height in JavaScript can conflict with @page { size: ... }. With preferCSSPageSize: false, the API paper is authoritative and CSS is fitted to it. With true, CSS owns the paper size. Mixing both without documenting the precedence is the most common source of “A4 is wrong” reports.
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 reinstall#1 Best Overall
- BEST FOR SMALL BUSINESSES – Engineered for extraordinary productivity, the Brother DCP-L2640DW Monochrome (Black & White) 3-in-1 combines laser printer, scanner, copier in one compact footprint and delivers high-quality black & white prints
- FAST PRINTER WITH EFFICIENT SCANNING – Produces documents quickly with print speeds up to 36 ppm(2) and scan speeds up to 23.6/7.9 ipm(3) (black/color). A 50-page auto document feeder(4) allows for convenient, time saving multi-page scanning and copying
- FLEXIBLE CONNECTION OPTIONS – Easily navigate the changing demands of your business with secure multi-device connectivity via built-in dual-band wireless (2.4GHz / 5GHz) and Ethernet. Or connect locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Print, scan, and manage your wireless printer anytime, from almost anywhere from your mobile device. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(5)
- CHOOSE BROTHER GENUINE TONER – When it’s time to replace your toner, be sure to choose Brother Genuine TN830 or TN830XL replacement toner. And with Refresh EZ Print Subscription Service, you’ll never worry about running out of toner again and you’ll enjoy savings of up to 50%(6) on Brother Genuine Toner. Get started with Refresh today with a Free Trial(1)
Implicit Letter defaults
Code that omits format, width and height silently gets Letter (8.5 × 11 inches). A4 is 21 × 29.7 cm, so a layout designed for A4 will reflow or paginate differently when it lands on Letter. Orientation and margins further reduce the usable content area.
Print CSS is a different layout
Because PDF generation selects print media, @media print rules may hide navigation, change widths, remove backgrounds or alter page breaks. To intentionally render screen rules instead, call await page.emulateMediaType('screen') before page.pdf(). This is a deliberate trade-off: screen styling may not paginate as cleanly as print styling.
Scale changes geometry inside the same paper
scale does not change the declared paper dimensions. It changes the size of rendered content inside that paper. A value below 1 can make more content fit; a value above 1 can push lines and blocks onto later pages. For predictable output, keep it at 1 unless you have a documented reason to change it.
Responsive units and viewport-dependent rules
Viewport-relative and other responsive rules can reflow in paged output. CSS behavior for viewport-related units in @page remains an area of standards discussion, so avoid relying on them for physical paper geometry. Prefer absolute units such as mm or in for the page box and margins.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- BEST FOR HOMES & HOME OFFICES – Engineered for consistent, premium print quality, the Brother HL-L2405W Monochrome (Black & White) Laser Printer delivers sharp, crisp prints at an affordable price. Prints one-sided documents at speeds up to 30ppm(2)
- COMPACT, CONNECTED PRINTER – Flexible connection options make this an ideal printer for home use and at-home offices. Securely connect to multiple devices with built-in dual-band wireless (2.4GHz/5GHz) or locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Manage your printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Enjoy seamless, reliable everyday printing with the 250-sheet paper tray(4) and a manual feed slot that enables printing on envelopes and specialty pape
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Late content, fonts and images
Pagination is calculated from the layout that exists when page.pdf() runs. Dynamic data, web fonts that have not finished loading and images without known dimensions can all change line wrapping and page breaks. Puppeteer’s PDF options document waitForFonts as enabled by default, but you should still wait for your own data and image-loading conditions.
Choose one geometry authority
Let CSS own the paper
Use this model when the HTML/CSS is the source of truth shared with browser printing or a design system. Define @page dimensions and margins, set preferCSSPageSize: true, and avoid a contradictory API format.
@page {
size: 210mm 297mm;
margin: 12mm;
}
@media print {
html, body { margin: 0; }
.screen-only { display: none !important; }
}Let the API own the paper
Use this model when a service contract requires a fixed paper size regardless of page-authored CSS. Pass explicit width, height, margins, orientation and scale. Remove or avoid conflicting @page size declarations and leave preferCSSPageSize at false.
A deterministic Puppeteer configuration
The following example uses A4 dimensions in millimetres, a 12 mm margin on every side and CSS as the declared page-size authority. It waits for network activity, fonts and an application-specific readiness flag before writing the PDF.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #3
- FAST PRINT SPEEDS: Print up to 19 pages per minute.
- COMPACT DESIGN: Space-saving, compact design fits anywhere in your home, school or small office.
- WIRELESS CONNECTIVITY: Print from almost anywhere in your workspace using your compatible mobile device.
- PAPER CAPACITY: Up to 150 sheets.
- SUSTAINABILITY: Uses less than 2 watts in Energy Saver mode.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 900, deviceScaleFactor: 1 });
await page.goto('https://example.com/report', { waitUntil: 'networkidle0' });
// Replace this selector with your app's real data-ready signal.
await page.waitForSelector('[data-report-ready="true"]');
await page.evaluate(() => document.fonts.ready);
await page.pdf({
path: 'report.pdf',
width: '210mm',
height: '297mm',
margin: { top: '12mm', right: '12mm', bottom: '12mm', left: '12mm' },
preferCSSPageSize: true,
printBackground: true,
scale: 1,
landscape: false,
displayHeaderFooter: false,
waitForFonts: true
});
await browser.close();If CSS owns the size, keep the @page declaration aligned with those dimensions. If the page has no readiness selector, wait for the application’s data promise or a deterministic DOM condition instead of adding an arbitrary delay.
Margins, backgrounds and pagination details
Understand the content box
Paper dimensions describe the outer page. Margins shrink the area available to your document. A 12 mm margin on all sides leaves less width for tables and less height for each page than a zero-margin PDF. Also check ordinary CSS margins on html, body and first or last children; those are separate from the PDF margin option.
Make print behavior explicit
Use printBackground: true when colored panels, background images or shaded table rows are part of the document. Hide screen-only controls in @media print, and set stable widths for tables and columns so a small content-box change does not trigger a cascade of line reflows.
Control breaks in CSS
Use print-aware break rules such as break-before, break-after and break-inside where a heading, card or table row must stay together. These rules cannot rescue content that is intrinsically taller than one page, so design oversized sections to split gracefully.
Recommended Free Tools
Rank #4
- BEST FOR HOME OFFICES & SMALL TEAMS – Engineered for consistent, premium print quality, the Brother HL-L2460DW Monochrome (Black & White) Laser Printer produces documents that are clear, crisp, and easy to review and share, all at an affordable price
- COMPACT, CONNECTED, EXCEPTIONALLY EFFICIENT– Connect with built-in dual-band wireless (2.4GHz/5GHz), Ethernet, or to a single computer via USB interface. Prints at speeds up to 36ppm(2), plus automatic duplex printing saves time and reduces paper waste
- BROTHER MOBILE CONNECT APP – Manage your wireless printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Tackle high-volume black & white printing with the 250-sheet capacity paper tray.(4) The manual feed slot enables printing on envelopes and specialty paper
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Diagnose a mismatch systematically
- Record the effective options. Log
format, dimensions, margins,landscape,scaleandpreferCSSPageSizefor every build. - Inspect print CSS. Temporarily emulate print in DevTools or remove
@media printrules one at a time to find a width, display or margin change. - Check the paper authority. Search for every
@pagerule and confirm whether CSS or the API is intended to win. - Verify readiness. Confirm that data, fonts and images are loaded before PDF generation; give images explicit dimensions where possible.
- Compare the content box. A paper-size match with different margins can still produce different wrapping and page counts.
- Freeze the environment. Keep the Puppeteer/Chromium version, viewport, fonts and locale consistent between local development and CI.
Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| “A4” output has Letter proportions | Format omitted, so Letter was selected | Set format: 'A4' or explicit 210 × 297 mm dimensions. |
@page size is ignored |
preferCSSPageSize is false |
Set it to true, or remove the CSS size and let the API own geometry. |
| Content is unexpectedly tiny | scale below 1, or CSS was fitted to a different paper |
Use scale: 1 and align the two size authorities. |
| Extra blank pages | Print widths, margins or late-loaded content overflow the page | Inspect print widths, wait for content, and remove unintended body margins. |
| Different page breaks in CI | Fonts, data, browser version or timing differ | Await fonts and data, pin the runtime, and use deterministic readiness checks. |
| Colors or backgrounds disappear | Background printing is disabled | Set printBackground: true and verify print CSS. |
| Screen layout is expected but print layout appears | page.pdf() intentionally uses print media |
Call emulateMediaType('screen') before generating the PDF. |
Performance, reliability and cost considerations
Waiting for networkidle0, fonts and application data improves determinism but can expose pages that never become idle because of analytics or long polling. In those cases, wait for a specific application-ready selector and use targeted request blocking rather than an indefinite idle condition. Cache or reuse browser processes carefully, but create an isolated page per job so cookies, viewport and print settings do not leak between documents.
For repeatable builds, store the generated PDF alongside the exact input URL or HTML, option object, browser version and font set. That metadata makes a one-pixel or one-page regression explainable instead of mysterious.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server when you need a rendered capture without maintaining your own Chromium pipeline. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status. Its PDF tool supports paper size, margins, landscape mode and page ranges.
One GET request returns an image or PDF. See the ScreenshotNeo API documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Developers can also use its MCP server with Claude, Cursor or another MCP client through take_screenshot, get_page_info and capture_pdf. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Best Value
- FROM AMERICA'S MOST TRUSTED PRINTER BRAND – Perfect for small teams printing professional-quality black & white documents and reports. Perfect for 1-3 people
- WORLD'S SMALLEST LASER IN ITS CLASS – Precision laser printing that fits anywhere
- FAST PRINT SPEEDS – Up to 21 black-and-white pages per minute single-sided
- WIRELESS WITH SELF-RESET – Helps you stay connected
- PRINT FROM ANY DEVICE – Wireless printing from any mobile device, PC or tablet. Works with Microsoft, Mac, AirPrint, Android, Chromebook and more
What to standardize in a team
- A single owner for paper geometry: CSS or API.
- Explicit paper dimensions, orientation, margins, scale and background policy.
- A print stylesheet that removes screen-only UI and defines stable widths.
- Readiness checks for data, images and fonts.
- A pinned Puppeteer/Chromium runtime and repeatable font installation in CI.
- Regression samples that verify page dimensions, page count and key break locations.
Frequently Asked Questions
Does changing the viewport change the PDF paper size?
The viewport can change responsive layout and line wrapping, but the PDF paper box is controlled by format, width/height, CSS @page and orientation. Keep both viewport and paper settings explicit when comparing builds.
Should I use format: 'A4' or millimetre dimensions?
Either is valid. Use the named format for standard paper; use explicit dimensions when you need a precise custom box or want the units to be obvious in configuration.
Why does the PDF have the right paper size but the wrong number of pages?
Page count depends on the available content box, print CSS, scale, fonts, images and dynamic data. Check margins and readiness after confirming the outer paper dimensions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
