Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If a Puppeteer PDF is missing CSS backgrounds, set printBackground: true in page.pdf(). If Chrome still changes or suppresses intended colors, add print-color-adjust: exact (and Chromium’s -webkit-print-color-adjust: exact) to the affected elements. Also inspect print-specific CSS: Puppeteer renders PDFs with the print media type by default.
Why are background colors missing in my Puppeteer PDF?
There are three separate causes that are often confused:
page.pdf()has aprintBackgroundoption whose documented default isfalse. With the default, background graphics are omitted.- PDF generation uses print CSS by default. Rules inside
@media printcan remove, replace or recolor backgrounds that are visible on screen. - Print rendering may optimize colors. The CSS
print-color-adjustproperty controls whether the user agent may alter authored colors and imagery.
Fix these in that order. The PDF option includes background graphics; the CSS property requests preservation of the colors you authored. One does not replace the other.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Official references: Puppeteer Page.pdf(), Puppeteer PDFOptions and MDN print-color-adjust.
#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)
The reliable Puppeteer fix
1. Enable background graphics
Pass printBackground: true when writing the PDF:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({headless: true});
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'networkidle0'});
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true
});
await browser.close();The option is a boolean. Its documented default is false, so explicitly setting it avoids relying on defaults or wrapper-library behavior.
2. Preserve colors that print rendering changes
Apply both the standard property and its WebKit-prefixed form to the component whose color matters:
@media print {
.colored-panel {
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
}Use this on panels, badges, table rows or other intentional color treatments rather than indiscriminately on the entire document. exact asks the browser not to optimize the element’s authored colors and images. It cannot force a physical printer, PDF viewer or user preference to produce a particular ink or display result.
Free tools Windows power users keep installed
One-click scans. No signup required.
3. Check print-only CSS
Search every stylesheet for @media print and inspect rules that set background, background-color, opacity, visibility or display. A common pattern is a screen card with a colored background and a print rule that sets background: transparent. Remove that override or add a more specific print rule:
@media print {
.invoice .total {
background-color: #17324d;
color: #fff;
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
}Do not assume a screen screenshot proves the print stylesheet is correct; the two media types can deliberately have different layouts and colors.
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
When to use screen media instead
Puppeteer documents that page.pdf() uses the print CSS media type. If the desired PDF should follow the screen stylesheet, call:
await page.emulateMediaType('screen');
await page.pdf({
path: 'screen-styled.pdf',
printBackground: true
});This is not a generic background-color fix. Screen media can change pagination, page breaks, widths and visibility, so verify the resulting document. Keep the default print media when the page has a deliberately designed print layout.
A complete diagnostic sequence
- Confirm the capture route. Determine whether your application calls Puppeteer’s
page.pdf()or Chrome’s command-line--print-to-pdf. They expose different controls. - Turn on backgrounds in Puppeteer. Add
printBackground: trueand regenerate the file. - Inspect computed print styles. Look for
@media printrules that remove backgrounds or change text and opacity. Use DevTools’ print emulation while developing. - Preserve essential colors. Add both
-webkit-print-color-adjust: exactandprint-color-adjust: exactto affected elements. - Choose the intended media type. Use
emulateMediaType('screen')only when screen styling, rather than print styling, is the requirement. - Check timing for dynamic pages. Wait for the application’s actual render condition, fonts and images before creating the PDF.
Dynamic content, fonts and images
Color can appear to be missing when the element itself has not finished rendering. waitUntil: 'networkidle0' is useful for many pages, but it is not proof that application code, web fonts or lazy images are ready. Prefer an explicit readiness signal:
await page.goto('https://example.com/report', {waitUntil: 'domcontentloaded'});
await page.waitForSelector('.report-ready');
await page.evaluate(() => document.fonts.ready);
await page.pdf({path: 'report.pdf', printBackground: true});For lazy-loaded content, scroll or trigger the site’s own loading mechanism before capture. A background applied by a client-side framework will not appear until that code has run.
Chrome Headless from the command line
Chrome’s documented command-line route is --print-to-pdf:
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.
google-chrome --headless --print-to-pdf=output.pdf https://example.comThe Chrome Headless command-line reference documents --timeout as a maximum wait in milliseconds and --virtual-time-budget as a way to advance time-dependent JavaScript:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →google-chrome --headless
--timeout=10000
--virtual-time-budget=5000
--print-to-pdf=output.pdf
https://example.comThese flags affect when capture occurs; they do not prove that external resources or an application-specific render step has completed. Validate the PDF against the page’s loading behavior.
The researched CLI reference does not document a command-line flag equivalent to Puppeteer’s printBackground PDF option. Do not treat CSS as a guaranteed replacement for that API setting. Check the flags supported by the Chrome version installed on your system. The reference also notes that the header/footer flag name changed, so older Chrome releases may require the previous spelling.
Common failures and fixes
Backgrounds are completely absent
Cause: printBackground was omitted or set to false. Fix: set it to true in the same page.pdf() call that writes the file.
Only some components lose their color
Cause: a component-specific @media print rule, lower specificity, transparency or an inherited style. Fix: inspect computed styles in print emulation and add a targeted print rule with the intended background and color-adjust properties.
Windows 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 reinstallCrashes, 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 minuteRank #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
Colors are present but look lighter or different
Cause: print color optimization. Fix: apply -webkit-print-color-adjust: exact and print-color-adjust: exact to the element. This is a request to preserve authored output, not a guarantee about a viewer or physical printer.
The PDF uses the wrong layout
Cause: switching to screen media changed pagination or print-only rules. Fix: remove emulateMediaType('screen') unless screen CSS is explicitly required, then repair the print stylesheet instead.
Colors appear intermittently
Cause: capture races with client-side rendering, fonts, images or lazy loading. Fix: wait for a page-specific selector, document.fonts.ready, image completion and any application readiness event before calling page.pdf().
The CLI output differs from Puppeteer
Cause: the two routes have different option surfaces and timing controls. Fix: reproduce the same URL, Chrome version and wait conditions, and consult the current Chrome Headless CLI documentation for supported flags.
Performance, reliability and cost considerations
- Reuse a browser process. For batches, keep one Chromium process open and create isolated pages or contexts instead of launching Chrome for every PDF.
- Wait for a meaningful condition. An explicit ready selector is usually more reliable than an arbitrary long delay. Use a timeout as a safety limit so a broken page cannot hold a worker forever.
- Control external assets. Missing fonts, blocked image hosts and authentication redirects can change contrast and layout. Capture with the same headers, cookies and network access as a real user.
- Keep color rules targeted. Exact color adjustment can preserve large areas of ink-heavy design. Apply it where fidelity matters, while recognizing that output-device settings remain outside browser control.
- Regression-test representative pages. Include light and dark panels, gradients, tables, lazy images, long pages and pages with print-specific CSS. Compare rendered PDFs after Chromium upgrades.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server when you need a hosted capture rather than maintaining Chromium code. It accepts a URL and can return PNG, JPEG, WebP or PDF. Before capture it accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; those cleanup steps can be switched off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
For PDF or image capture, see the ScreenshotNeo documentation. A one-call request looks like this:
Best Value
- HP LaserJet M209dw Wireless Printer, Print, Fast speeds, Easy setup, Mobile printing, Best-for-small teams, Instant Ink eligible
- Perfect for small teams printing black & white documents and reports, plus auto two-sided printing. Perfect for 1-5 people
- FASTEST TWO-SIDED PRINTING IN ITS CLASS – Up to 30 black-and-white pages per minute single-sided, u up to 19 black-and-white images per minute two-sided printing
- DUAL-BAND WI-FI WITH SELF-RESET – Automatically detects and resolves connectivity issues
- STRONG SECURITY – Built-in security features help protect your printer from potential attacks
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpThe same request in Python:
import 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)And Node.js:
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every plan includes the capture options, including full-page shots with lazy images loaded, CSS-selector elements, dark mode, device and viewport controls, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work for easier migration.
ScreenshotNeo’s Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Sign up for the free plan.
FAQ
Does print-color-adjust: exact turn backgrounds on?
No. In Puppeteer, enable printBackground: true first. The CSS property addresses color optimization after background graphics are included.
Will a PDF always match the colors on my monitor?
No. Browser print preferences, PDF viewers, printers and output devices can still affect the final appearance.
Should I always emulate screen media?
No. Use screen media only when the PDF is intended to follow screen styles. Otherwise, repair the print stylesheet and keep Puppeteer’s default print media.
Frequently Asked Questions
Can I solve this only with CSS?
Not reliably in Puppeteer. CSS can request exact color preservation, but background graphics still require the PDF option printBackground: true.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Which Chrome flag replaces printBackground?
The documented Chrome Headless CLI reference does not specify an equivalent flag. Use Puppeteer when you need that PDF option explicitly.
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.
