How to Preserve Background Colors in Puppeteer PDFs

Set printBackground: true in the options passed to page.pdf(). Puppeteer leaves background graphics off by default, so this explicit option is required. For colors that match the screen, also use -webkit-print-color-adjust: exact and choose deliberately between print and screen media before exporting.

The minimum fix

Here is a complete Puppeteer example that loads a page and preserves its CSS background graphics:

#	Preview	Product	Price
1		PDF Explained: The ISO Standard for Document Exchange	$14.41	Buy on Amazon
2		Adobe Acrobat 6 PDF For Dummies	$13.00	Buy on Amazon
3		Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware...	$13.39	Buy on Amazon

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  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();
})();

printBackground is optional and defaults to false in Puppeteer’s current PDFOptions reference. Setting it to true tells Chromium to print background graphics, including CSS background colors and images.

Why colors can still look different

Enabling background graphics solves only one part of the problem. page.pdf() generates a PDF using the print CSS media type by default, and Puppeteer documents that colors are modified for printing. Print stylesheets may also hide elements, change colors, or use different layouts.

#1 Best Overall

Sale

PDF Explained: The ISO Standard for Document Exchange

$14.41

Buy on Amazon

To request exact CSS colors, add this rule:

html {
  -webkit-print-color-adjust: exact;
}

The declaration controls color adjustment; it does not replace printBackground: true. Use both when backgrounds must appear and their specified colors should be retained.

Print media versus screen media

Choose the media type based on the stylesheet you want Chromium to apply. Do not switch to screen media automatically: doing so can bypass intentional print layout rules such as page breaks, compact navigation, or print-only content.

Use the default print media

Print media is appropriate for invoices, reports, and documents that have a dedicated print stylesheet.

await page.pdf({
  path: 'report.pdf',
  printBackground: true
});

Add -webkit-print-color-adjust: exact in the page’s CSS when the print rendering should keep the declared colors.

Use screen media

If the PDF should reproduce the on-screen design, emulate screen media before exporting:

await page.emulateMediaType('screen');
await page.pdf({
  path: 'screen-layout.pdf',
  printBackground: true
});

This changes which @media rules apply. Keep printBackground: true; screen emulation does not enable background printing by itself.

Compare the choices

A production-ready export

Real pages often build their content asynchronously. Wait for the page’s data, images, and layout according to your application before calling page.pdf(). Puppeteer’s PDF guide notes that PDF generation waits for fonts by default, but that does not prove every external resource has finished loading.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true
  });

  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });

    await page.goto('https://your-site.example/report', {
      waitUntil: 'domcontentloaded',
      timeout: 60000
    });

    await page.waitForSelector('#report-ready', { timeout: 30000 });
    await page.evaluate(() => document.fonts.ready);

    // Select this only when the screen stylesheet is the desired layout.
    // await page.emulateMediaType('screen');

    await page.pdf({
      path: 'report.pdf',
      format: 'A4',
      printBackground: true,
      preferCSSPageSize: true,
      margin: { top: '16mm', right: '16mm', bottom: '16mm', left: '16mm' }
    });
  } finally {
    await browser.close();
  }
})();

preferCSSPageSize is useful when the document defines its own @page size; remove it if the explicit Puppeteer format should always win. The margins and page format are independent of background preservation.

Rank #2

Sale

Adobe Acrobat 6 PDF For Dummies

• Used Book in Good Condition

$13.00

Buy on Amazon

Do not confuse omitBackground with printBackground

These options do opposite jobs:

• printBackground: true enables background graphics that would otherwise be omitted.
• omitBackground: true hides the default white page background and allows transparency.

For a normal colored page, leave omitBackground unset (or false) and set printBackground: true. Use omitBackground only when a transparent PDF is specifically required.

CSS patterns that survive PDF export

Apply exact color adjustment globally

html, body, .card, .banner {
  -webkit-print-color-adjust: exact;
  print-color-adjust: exact;
}

-webkit-print-color-adjust is the property Puppeteer’s API documentation specifically recommends. The unprefixed print-color-adjust can be included as a standards-oriented companion, while Chromium’s prefixed property is the important compatibility declaration for this workflow.

Keep print overrides intentional

@media print {
  .screen-only { display: none; }
  .invoice-header {
    background: #16324f;
    color: #fff;
    -webkit-print-color-adjust: exact;
  }
}

If you emulate screen media, this block will not apply. Put rules that must work in both modes outside media queries, or test each mode separately.

Remember element backgrounds

Backgrounds on child elements, gradients, and background images are all graphics from the PDF option’s perspective. A white page with a colored card can therefore require both the option and color-adjustment CSS even when the body itself has no background.

Troubleshooting missing or inaccurate colors

Backgrounds are completely absent

• Confirm the option is on the object passed to page.pdf(), not to page.goto().
• Check that omitBackground is not being set for a transparent export.
• Verify that the CSS selector actually matches in the loaded page and that a print rule is not removing the element or setting background: none.

The PDF uses the wrong layout

That is usually a media-type issue. Inspect @media print rules and either keep the default print behavior or call await page.emulateMediaType('screen') before export. Screen mode can also remove intended print page breaks, so test pagination after switching.

Colors are washed out or changed

Add -webkit-print-color-adjust: exact to the affected elements or a suitable ancestor. Ensure the declaration is not overridden later by a more specific rule. This controls Chromium’s print color adjustment; it cannot repair a different color explicitly supplied by a print stylesheet.

Images or web fonts are missing

Wait for the application-specific ready condition, then wait for fonts with document.fonts.ready. For images, wait for a known image selector or evaluate the document’s image completion state. A networkidle0 navigation wait is helpful but is not a guarantee for pages that continue polling or render data after navigation.

The export times out

Use a realistic timeout, diagnose the slow request, and avoid waiting for network idle on an application with persistent analytics or sockets. A deterministic #report-ready marker is generally more reliable than an arbitrary delay.

Rank #3

Sale

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

• Used Book in Good Condition

$13.39

Buy on Amazon

Results differ between machines

Puppeteer bundles or launches a particular Chromium build, while system fonts, installed dependencies, and your Puppeteer version affect rendering. The current API pages are labeled version 25.12.0; older installed versions may differ. Check the local dependency and browser version, pin them in CI, and compare generated PDFs in the same environment.

Verification checklist

• Set printBackground: true.
• Decide whether print or screen media is correct before export.
• Add -webkit-print-color-adjust: exact where exact colors matter.
• Wait for application data, images, and fonts.
• Check omitBackground is not accidentally enabled.
• Test page breaks, margins, and CSS @page rules in the chosen media mode.
• Pin Puppeteer and Chromium versions for repeatable CI output.

Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server when you need an image or PDF without maintaining Puppeteer and Chromium. A single GET request can return a PNG, JPEG, WebP, or PDF. For example, this cURL request captures a page as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for PDF parameters and the full option set. The service can accept consent banners before capture and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed as clean shots, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

It also supports full-page captures with lazy images loaded, CSS-selector element captures, dark mode, device presets or custom viewports, retina scale, PDF paper size and margins, page ranges, custom CSS and JavaScript, pre-capture clicks, selector hiding, waits for selectors or network idle, request and ad blocking, custom headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification.

The 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, and every feature is available on every plan. Create a free ScreenshotNeo account to try it.

Relevant Puppeteer references

• PDFOptions interface: option defaults and descriptions, including printBackground and omitBackground.
• Page.pdf() method: print media behavior and exact-color guidance.
• PDF generation guide: the launch, navigation, export, and close workflow.

Frequently Asked Questions

Does `printBackground: true` preserve every color exactly?

No. It enables background graphics. For color adjustment, add `-webkit-print-color-adjust: exact`; also choose the media type whose CSS rules you intend to render.

Can I make a transparent Puppeteer PDF?

Use the separate `omitBackground: true` option. This is different from enabling background graphics with `printBackground`.

Should I always emulate screen media?

No. Use screen media only when the screen stylesheet is the desired PDF layout. Otherwise retain Puppeteer’s default print media.

Which Puppeteer version does this guidance describe?

The cited current API pages are labeled version 25.12.0. Verify your installed Puppeteer and bundled Chromium because older versions and environments can behave differently.

Quick Recap

SaleBestseller No. 1

PDF Explained: The ISO Standard for Document Exchange

$14.41

SaleBestseller No. 2

Adobe Acrobat 6 PDF For Dummies

Used Book in Good Condition

$13.00

SaleBestseller No. 3

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

Used Book in Good Condition

$13.39

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.