To print a background in a Puppeteer PDF, define the image in print CSS, call page.pdf() with printBackground: true, and then verify a multi-page fixture in the exact Chromium version you deploy. Use background-repeat: repeat or repeat-y when you want a tile inside an element; if you need one image on every physical sheet, test a page-level @page rule or a page-sized layout element because element backgrounds and PDF page backgrounds are different rendering problems.
What Puppeteer actually prints
Puppeteer’s Page.pdf() method generates a PDF with the print CSS media type. Consequently, styles that exist only in a screen stylesheet may not be active. Put the image rules in a print stylesheet or an @media print block. Puppeteer’s printBackground option defaults to false; setting it to true permits background graphics to be included, but it does not add an image or choose how it repeats.
There are two meanings of “repeat on every page”:
| Goal | Relevant mechanism | What to verify |
|---|---|---|
| Tile an image through a content region | background-image plus background-repeat on an element |
The element’s painted area continues across the page fragments you expect |
| Place an image on every physical PDF sheet | A tested @page rule or a page-sized document layout |
Browser support, margins, clipping, page breaks and the deployed Chromium build |
MDN describes background-repeat as repeating an image as needed to cover its background painting area. That painting area belongs to the element; it is not automatically reset for each PDF sheet.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#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)
A minimal multi-page Puppeteer implementation
The following fixture deliberately creates several pages so you can inspect the first page, a page break and the final page. Replace the data URL with your own image or a URL that your deployment can load.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(`
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
@page {
size: A4;
margin: 18mm 16mm 20mm;
}
@media print {
html, body { margin: 0; }
body {
background-image: url("https://example.com/assets/paper-tile.png");
background-repeat: repeat;
background-position: top left;
background-size: 160px 160px;
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
.section { break-after: page; min-height: 240mm; }
.section:last-child { break-after: auto; }
}
</style>
</head>
<body>
<section class="section"><h1>Page one</h1><p>Content...</p></section>
<section class="section"><h1>Page two</h1><p>Content...</p></section>
<section class="section"><h1>Page three</h1><p>Content...</p></section>
</body>
</html>`);
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true,
preferCSSPageSize: true
});
await browser.close();
})();In this example, repeat tiles both axes. Use repeat-y for a vertical-only tile, repeat-x for horizontal-only repetition, and no-repeat for a single placement. If the painted area is not an exact multiple of the image dimensions, edge tiles can be clipped; that is normal CSS tiling rather than a PDF error.
Choose the right CSS repetition strategy
Tile an element’s background
Apply the background to the element whose box should be painted:
@media print {
.report {
background: url("/img/grid.png") top left / 120px 120px repeat;
}
.report-sidebar {
background-image: url("/img/rule.png");
background-repeat: repeat-y;
}
}A body or wrapper background may paint continuously through the document’s layout, but pagination can fragment that layout in ways that do not correspond to a fresh canvas on each sheet. Check whether the background is attached to a box that spans all required content and whether page breaks create new boxes.
Attempt a page-level background
The @page at-rule targets printed pages and can define page size, orientation and margins. A page-level background can be appropriate when the requirement is a physical-sheet design rather than a content-region tile:
@page {
size: A4 portrait;
margin: 18mm;
background: url("/img/letterhead.png") center / cover no-repeat;
}Support for individual @page features varies by browser and version. Treat this as a version-specific approach to validate, not a universal guarantee. The MDN @page reference documents the rule and its support caveats. Chrome’s page-margin features also evolve; the Chrome for Developers article on print margins describes page-margin content support in Chrome 131.
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
Use a page-sized layout when page rules are insufficient
For deterministic stationery, create a repeated page component whose dimensions match the printable area, put the image on that component, and insert explicit page breaks:
@media print {
.pdf-page {
position: relative;
min-height: 259mm; /* A4 height minus the chosen margins */
break-after: page;
background: url("/img/letterhead.png") center / cover no-repeat;
}
.pdf-page:last-child { break-after: auto; }
}This gives you a separate painted box per page, but it also makes content height, margins and overflow your responsibility. A long paragraph can force an unexpected extra sheet unless you manage its flow.
Coordinate page size, margins and scaling
CSS and Puppeteer must describe the same paper. You can set format, or specify width and height, while CSS sets an @page size. Puppeteer’s preferCSSPageSize option gives the CSS @page size priority over format, width or height; otherwise content may be scaled to fit the selected paper.
await page.pdf({
path: 'output.pdf',
printBackground: true,
preferCSSPageSize: true,
margin: {
top: '0',
right: '0',
bottom: '0',
left: '0'
}
});Do not accidentally define a 20 mm CSS margin and another 20 mm Puppeteer margin unless that double inset is intentional. Compare the generated page dimensions with the CSS page size and inspect whether the image reaches the trim edge, stops at the margin box or is clipped.
Make sure the image is ready before PDF generation
Puppeteer’s PDF guide says PDF generation waits for fonts by default. That statement does not guarantee that every externally loaded CSS image has completed. For remote assets, wait for the image explicitly or preload it:
await page.setContent(html, { waitUntil: 'networkidle0' });
await page.evaluate(() => Promise.all(
[...document.images].map(img => img.complete
? Promise.resolve()
: new Promise(resolve => {
img.addEventListener('load', resolve, { once: true });
img.addEventListener('error', resolve, { once: true });
}))
));
CSS background images are not represented by document.images. For those, preload the URL with a hidden image, use a same-origin asset, or wait for an application-specific readiness signal. Also check that the PDF process can resolve the hostname, authenticate to the asset and pass any content-security policy requirements.
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.
Print colors and media selection
Because page.pdf() uses print media, put print-only rules in @media print. If the intended output is the screen design instead, Puppeteer documents selecting screen media before creating the PDF:
await page.emulateMediaType('screen');
await page.pdf({ path: 'screen-styled.pdf', printBackground: true });Choose one media model deliberately; do not assume screen and print styles match. Chromium can modify colors for printing. Use -webkit-print-color-adjust: exact (and the standard print-color-adjust declaration where appropriate) when exact color reproduction matters, then verify the resulting PDF on your target Chromium version and printer/viewer.
Verification checklist for every-page backgrounds
- Generate at least three pages, including an intentional page break and a final page with different content height.
- Open the PDF and inspect the first, middle and last sheets at 100% zoom.
- Check for missing images, white pages, clipped edges, shifted margins, repeat seams and unexpected scaling.
- Confirm that a page with a large image and a page with little content behave the same way.
- Record the Puppeteer and Chromium versions used in CI; rerun the fixture after upgrades.
- Test both a local asset and the production delivery path if your image is remote.
Troubleshooting common failures
The background is completely missing
Most often, printBackground is still false or the rule is screen-only. Set printBackground: true, move the declaration into print CSS, and confirm the image request succeeds in the page context.
The image appears on page one but not later pages
The background may belong to an element whose painted box ends at the first fragment, or the chosen page-level rule may not be supported by that Chromium build. Try a page-sized repeated component, then compare it with a tested @page implementation. A multi-page fixture is the deciding test.
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 →Only part of each tile is visible
Inspect background-size, the element’s dimensions and the paper margins. Tiling clips at the painting area’s edges by design. If the image must cover the entire sheet, use a page-sized box with background-size: cover and account for overflow.
The PDF has unexpected borders or a shrunken image
Look for margins specified in both CSS and page.pdf(). Set preferCSSPageSize consistently and remove accidental default margins. Check whether Puppeteer scaled content to fit because the paper settings disagree.
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
The remote image is intermittently blank
Wait for the asset, avoid expiring signed URLs, and ensure the browser process can reach the host. For a CSS background, preload the same URL or expose an application-ready promise; do not rely solely on networkidle0 when the page keeps long-lived connections open.
Colors differ from the browser preview
Print color adjustment is affecting the result. Add the print-color-adjust declarations, keep the rule in the active media type, and compare output from the deployed browser rather than a different local version.
Recommended Free Tools
Performance and reliability considerations
Large repeated images increase decoding and PDF rasterization work, especially with high device scale factors or full-page layouts. Prefer a suitably sized tile instead of a multi-megapixel photograph when the pattern does not need photographic detail. Keep assets local or on a low-latency origin, cache immutable files, and avoid generating a new signed image URL for every tile.
For batch jobs, reuse a browser where safe, but create a fresh page per document so CSS, cookies and failed resources do not leak between jobs. Set an upper bound on navigation and asset waits, log the page URL and browser version, and retain a failed PDF fixture for diagnosis. Reliability comes from testing the exact rendering path, not from assuming that one CSS rule behaves identically in every Puppeteer/Chromium release.
Or skip the browser setup
If your task is simply to obtain a clean screenshot or PDF of a URL rather than render a custom Puppeteer document, ScreenshotNeo provides a website screenshot API and MCP server. 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 or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
One GET request returns PNG, JPEG, WebP or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for output and options. Equivalent requests in Python and Node.js are:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsimport 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}`);ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. Every plan includes its features; the Free plan provides 1,000 shots per month without a card, and paid plans start at $5 for 3,000 shots. Start with the 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
FAQ
Does background-repeat automatically restart on each PDF page?
No. It repeats within the element’s background painting area. Restarting or positioning an image per physical sheet requires a page-level or page-component design that you verify in your browser build.
Should I use format or @page size?
Use one deliberate source of truth. If CSS should control paper dimensions, set preferCSSPageSize: true; otherwise let Puppeteer’s paper option control the output and test scaling.
Why does a CSS background image load differently from an inline image?
CSS backgrounds are not exposed through document.images, so an image-completion check for inline images will not prove that a background is ready. Preload the URL or wait for an application-specific readiness signal before calling page.pdf().
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 reinstallFrequently Asked Questions
Can I guarantee identical page backgrounds across all Puppeteer versions?
No. Page-level CSS support and pagination behavior can vary with the bundled Chromium release, so keep a multi-page regression fixture and test the version you deploy.
What is the safest design for letterhead on every sheet?
Use a repeated, page-sized component with explicit page breaks when you need predictable per-sheet painting; use @page only after validating its background behavior in your target build.
The Bottom Line
Enable print backgrounds, define the image in print CSS, align CSS and Puppeteer page geometry, wait for assets, and test a real multi-page PDF. Choose element tiling for a content region and a validated page-level or page-sized design for one image on every physical sheet.
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.
