If a background color stops at a page break in a Puppeteer PDF, fix the capture settings and the print layout together: enable printBackground, use the intended media type, make the color print-safe, and control whether the colored element may fragment. A reliable baseline is page.emulateMediaType('screen') (when the design is screen CSS), printBackground: true, and CSS rules for print-color-adjust and page breaks.
Use this baseline fix first
Apply the following JavaScript before diagnosing more unusual layouts:
await page.emulateMediaType('screen'); // Omit when print CSS is intentional
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true,
preferCSSPageSize: true
});Then make the relevant element explicitly printable:
.colored-section {
background: #eef3ff;
print-color-adjust: exact;
-webkit-print-color-adjust: exact;
}
@media print {
.colored-card {
break-inside: avoid;
page-break-inside: avoid; /* legacy alias */
}
}This combination addresses the four most common causes: Puppeteer selecting print media rules, backgrounds being disabled for PDF output, the browser economising on ink, and a box being split into page fragments.
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
Why the color disappears or stops at a break
Puppeteer renders print media by default
page.pdf() generates a PDF with the print CSS media type. Any rule inside @media print can therefore override the screen stylesheet, including background, background-image, dimensions, overflow, and visibility. If the screen design is the one you want in the PDF, call await page.emulateMediaType('screen') before creating the PDF. If you deliberately maintain a print stylesheet, leave the default in place and inspect that stylesheet instead.
Backgrounds are opt-in for PDF output
Puppeteer’s printBackground option defaults to false. With that default, text and borders may print while authored background colors and images do not. Set printBackground: true on the actual page.pdf() call; setting it on a wrapper function or a different page has no effect.
Printing can adjust colors
Browsers commonly remove or alter backgrounds when printing. print-color-adjust: exact asks the browser to preserve the authored colors, and the WebKit-prefixed form improves compatibility with Chromium versions that still consult it. This is a request rather than an absolute override: a user’s print preferences can still permit color reduction.
A box crossing a page is fragmented
A colored element taller than the remaining space is split into fragments. The background you see may appear to end at the first fragment, restart on the next, or be clipped by the element’s layout. This is pagination behavior, not necessarily a missing color declaration. Use break-inside: avoid (and its legacy page-break-inside: avoid alias) for cards, figures, tables, and sections that should stay together. An element taller than a page cannot be forced to fit by that rule; it must still fragment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Build a complete Puppeteer example
The following script waits for the page to settle, selects the desired media mode, and writes a PDF with backgrounds enabled. Replace the URL and output path for your project.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
try {
const page = await browser.newPage();
await page.setViewport({ width: 1440, height: 1000, deviceScaleFactor: 1 });
await page.goto('https://example.com/report', {
waitUntil: 'networkidle0',
timeout: 60000
});
// Use screen rules for a screen-designed document.
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' },
scale: 1
});
} finally {
await browser.close();
}If your document has a dedicated print stylesheet, remove the emulateMediaType('screen') line and fix the background in the print rules instead.
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
Keep short colored components on one page
Apply the break rule to the element that owns the background, not only to an inner child:
.colored-card {
background: #eef3ff;
padding: 20px;
break-inside: avoid;
page-break-inside: avoid;
print-color-adjust: exact;
-webkit-print-color-adjust: exact;
}This works when the card can fit in the available fragmentainer height. Large cards, long tables, and sections containing an unbreakable image will still split when there is no legal one-page placement.
Choose a strategy for sections that must span pages
Keep the entire box together
Use break-inside: avoid for a component that is short enough to fit on one page. Expect the browser to move it to the next page rather than leave a partial card behind.
Repeat decorations on every fragment
When a section is intentionally longer than one page, use box-decoration-break: clone if each page fragment should receive its own padding, border, and background decoration. Test this in the Chromium version used by your Puppeteer build because fragment decoration details can vary.
Use a continuous sliced decoration
box-decoration-break: slice treats the box decoration as one continuous decoration sliced at the page boundary. This can be appropriate for a long panel where a single visual field should continue across pages. Put the background on the element that actually fragments; a background on a non-fragmenting wrapper will not repair a child’s split.
Check page geometry, not just color settings
Pagination is calculated from the available height after paper size, margins, and scaling are applied. A one-line change can move a break into the middle of a colored panel.
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 →Clear out junk files and repair common Windows errorsFree Scan →Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
- Paper size:
format: 'A4'is different from explicitwidthandheight. - CSS page size: an
@pagerule can define its own size.preferCSSPageSize: truegives that CSS size precedence over Puppeteer’s format. - Margins: larger margins reduce the content area and can force an earlier fragment.
- Scale: values below or above
1change the effective layout and break positions. - Orientation: landscape and portrait provide different fragment heights.
Keep the geometry explicit while debugging:
@page {
size: A4;
margin: 16mm;
}
html, body {
margin: 0;
}
.report {
background: #eef3ff;
print-color-adjust: exact;
-webkit-print-color-adjust: exact;
}Do not set both a conflicting CSS page size and Puppeteer dimensions unless you have decided which one should win.
A diagnostic workflow that isolates the cause
- Inspect print computed styles. In DevTools, switch rendering to print media and inspect the affected element. Confirm its computed
background-colororbackground-imageis still present. - Verify the real PDF call. Search for every
page.pdf()invocation and confirm the one producing the failing file containsprintBackground: true. - Decide on media mode. Compare the output with print media and with
page.emulateMediaType('screen'). Keep the mode that matches the intended design. - Find the fragmenting owner. Temporarily add an outline to the element carrying the background. If that outline crosses the page, the element is being fragmented.
- Test a break rule. Add
break-inside: avoid. If the whole component moves to the next page, pagination—not color inheritance—was the issue. - Test decoration behavior. For a deliberately long panel, compare
box-decoration-break: cloneandslicein the target Chromium version. - Minimise the document. Reproduce the colored element with only its essential CSS, then add production rules back. Pay particular attention to inherited print rules,
overflow, transforms, positioned elements, and layout changes. - Compare versions. Generate the same fixture with the Chromium bundled by your deployed Puppeteer version. A result seen in a desktop browser is not a guarantee for a different headless build.
Common symptoms and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| All backgrounds are missing | printBackground remains at its default |
Set printBackground: true in the producing page.pdf() call. |
| Screen color appears, but PDF uses a white or alternate color | Print CSS is active | Use emulateMediaType('screen'), or correct the @media print rule. |
| Color is present on page one but absent on later pages | The element is fragmented and its decoration is not behaving as intended | Keep it together when possible; otherwise test box-decoration-break: clone or slice. |
| A card moves but still clips | The card is taller than the available page area, or an ancestor clips overflow | Reduce content, adjust geometry, remove inappropriate overflow, or design the card to fragment. |
| The break occurs in a different place after a CSS change | Paper size, margins, scale, or CSS page size changed | Make those values explicit and check preferCSSPageSize. |
| Colors differ between machines | Print preferences or Chromium versions differ | Use the color-adjust properties, standardize the browser build, and validate the generated PDF in your deployment environment. |
| Images or fonts shift the panel boundary | Capture happened before late resources settled | Wait for the required selector, fonts, images, or network idle before calling page.pdf(). |
Reliability and performance considerations
Wait for the state you actually need
networkidle0 is useful for mostly static pages, but analytics, chat, and streaming requests may prevent it from completing. In that case, wait for a report selector, a known application-ready flag, or a bounded delay. A PDF generated before a lazy image expands can move every later page break.
Use deterministic dimensions
Set the viewport, paper size, margins, scale, and device scale factor deliberately. Avoid depending on a developer laptop’s default viewport. If content changes by locale or timezone, set those inputs as part of the capture setup and test the longest expected text.
Keep break-sensitive CSS simple
Transforms, absolute positioning, nested overflow containers, and very large unbreakable children make pagination harder to predict. Prefer normal document flow for long reports, and apply the background to the flow element whose fragments you want to decorate.
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 minuteOr skip the browser setup
For a one-call screenshot or PDF workflow, ScreenshotNeo accepts a URL and returns a PNG, JPEG, WebP, or PDF. It handles 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 the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
For a PDF, you can still control paper size, margins, landscape mode, page ranges, waits, custom CSS and JavaScript, selectors, device presets, dark mode, headers, cookies, user agents, authorization, timezone, geolocation, resource blocking, caching TTL, signed links, asynchronous webhooks, and bulk capture. See the ScreenshotNeo documentation for parameter names and response details.
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}`);The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is included on every plan. Create a free ScreenshotNeo account to try it.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
FAQ
Does print-color-adjust: exact force color on every printer?
No. It requests authored colors, but user print preferences can override the request. Automated PDF generation should still use printBackground: true.
Should I always emulate screen media?
No. Use screen media when the PDF should match the screen design. Keep print media when your print stylesheet is intentional, then repair the background there.
Can break-inside: avoid prevent every split?
No. It cannot keep an element taller than the available page area on one page. Such an element needs a deliberate fragment strategy.
Frequently Asked Questions
Does print-color-adjust: exact force color on every printer?
No. It requests authored colors, but user print preferences can override the request. Automated PDF generation should still use printBackground: true.
Should I always emulate screen media?
No. Use screen media when the PDF should match the screen design. Keep print media when your print stylesheet is intentional, then repair the background there.
Can break-inside: avoid prevent every split?
No. It cannot keep an element taller than the available page area on one page. Such an element needs a deliberate fragment strategy.
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.
