What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
To make a Puppeteer PDF include the styles and images you expect, choose the right media type, enable CSS backgrounds, and wait for the page’s actual render-ready state. page.pdf() uses print CSS by default, and its printBackground option defaults to false. Neither option, on its own, guarantees that asynchronously loaded or lazy-loaded foreground images are ready.
Use the media type that matches the PDF you want
Puppeteer’s Page.pdf() renders with the print CSS media type by default. That is appropriate when the PDF should follow print-specific rules such as @media print. If instead the PDF should resemble the page as it appears on screen, switch to screen media before generating it:
As an Amazon Associate I earn from qualifying purchases.
await page.emulateMediaType('screen');Make this choice before page.pdf(). Switching media can change more than colors: print styles may hide navigation, alter layout, or change element visibility. The Puppeteer Page API documents PDF rendering and print color behavior.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallEnable CSS background graphics
Set printBackground: true to include CSS background graphics such as background colors and images. The option defaults to false. It controls backgrounds; it is not a general switch for loading ordinary foreground <img> elements.
#1 Best Overall
await page.pdf({
path: 'output.pdf',
printBackground: true,
});For colors that change during print rendering, the Page API points to the CSS property -webkit-print-color-adjust. For example, a page’s print stylesheet can use -webkit-print-color-adjust: exact when preserving specified colors is important. Check the rendered result in the browser version used in production; print CSS and browser rendering both affect the output.
Wait for fonts, images, and application rendering
Fonts
Puppeteer’s PDF options document waitForFonts: true as the default, and its PDF guide says Page.pdf() waits for fonts by default. You can set it explicitly to make the intended behavior clear. If text still uses a fallback typeface, check that the font requests succeed and that the page’s font-loading logic has completed.
Rank #2
Foreground and lazy-loaded images
For missing foreground images, inspect the image elements, their request status, and whether the application only loads them after scrolling or another interaction. A quiet network is not proof that a lazy image was requested, that client-side hydration finished, or that every component has rendered. Wait for a meaningful condition from the page or application when those behaviors apply.
Network idle and app-ready signals
You can use navigation lifecycle events or page.waitForNetworkIdle() to wait for network activity to settle. Puppeteer defines networkidle0 and networkidle2 as a 500 ms quiet period with no more than zero or two active connections, respectively. waitForNetworkIdle() documents a default idle time of 500 ms. These are network conditions, not guarantees that site-specific rendering is complete.
If your application exposes a documented ready flag, selector, or other completion condition, await it after navigation and before producing the PDF. Do not substitute a fixed delay for a reliable signal unless the application has no better condition and the delay is appropriate to your workload.
A practical Puppeteer sequence
This example uses screen media; remove the media switch to retain Puppeteer’s default print media. Replace the illustrative app-ready condition with one your page actually provides, or remove it if no such condition applies.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
// Use this only when the PDF should follow screen CSS instead of print CSS.
await page.emulateMediaType('screen');
// Replace with a real condition exposed by your application, if applicable.
// await page.waitForFunction(() => window.appRenderComplete === true);
await page.pdf({
path: 'output.pdf',
printBackground: true,
waitForFonts: true,
});
} finally {
await browser.close();
}For print-oriented output, omit emulateMediaType('screen') and provide print styles. The Puppeteer PDF generation guide recommends Page.pdf() for PDF printing.
Set page dimensions and color behavior deliberately
When the PDF’s paper size, margins, or scale are wrong, review the relevant PDF options rather than changing image-loading waits. Puppeteer documents format, width, height, margin, scale, and preferCSSPageSize. Use explicit dimensions when the PDF needs a specific paper size; consider preferCSSPageSize when the page’s @page CSS rule should determine the size.
Best Value
- Used Book in Good Condition
| Decision | Use |
|---|---|
| Print CSS or screen CSS | Print is the default. Call page.emulateMediaType('screen') before PDF generation when screen rules should apply. |
| Include CSS backgrounds | Set printBackground: true; the documented default is false. |
| Wait for network quiet or application readiness | Use navigation lifecycle events or waitForNetworkIdle() for network inactivity; use an application-specific condition when rendering continues after requests settle. |
| Set PDF dimensions | Review format, width, height, margins, scale, and preferCSSPageSize against the page’s CSS and output requirements. |
Troubleshoot missing images or styles
- Layout differs from the browser: check whether print CSS is active. If the PDF should use screen rules, call
emulateMediaType('screen')beforepage.pdf(). - Colored areas or background images are absent: set
printBackground: true. - Foreground images are absent: inspect their network requests and DOM state. Check lazy-loading triggers, hydration, and application rendering; network idle alone does not establish that the images were loaded.
- Text uses the wrong font: verify font requests and page font-loading behavior. Puppeteer’s documented default is to wait for fonts, but failed font resources can still produce fallback text.
- Print colors look different: review print CSS and consider
-webkit-print-color-adjust; validate with the deployed browser version. - Page size or scaling is wrong: check
format,width,height,preferCSSPageSize, margins, andscale. - The output is intermittently incomplete: replace assumptions based only on a network-idle event or arbitrary delay with a page-specific render-ready condition where possible.
Record versions when reproducing a PDF issue
The official Puppeteer API references identify version 25.12.0, dated 2026-09-23 in the Puppeteer changelog; that release records a roll to Chrome 154.0.8037.57. Rendering can depend on the browser/runtime, so record your deployed Puppeteer and browser versions when comparing output or investigating a regression.
Or skip the browser setup
If you need a website screenshot rather than a Puppeteer-generated PDF, ScreenshotNeo provides a screenshot API and MCP server. Its PDF option is available through the same service. The API accepts a URL and returns a PNG, JPEG, WebP, or PDF; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers indicating the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Recommended Free Tools
Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Does printBackground: true make Puppeteer wait for every image?
No. It enables CSS background graphics. Foreground image loading and application rendering need to be checked and awaited separately.
Which Puppeteer version should I report when a PDF looks different?
Record the Puppeteer and browser/runtime versions actually deployed; rendering behavior can depend on both.
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.
