iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To make a Puppeteer PDF header or footer keep its background color, enable header/footer rendering, set printBackground: true, and add -webkit-print-color-adjust: exact inside each template. Apply the color directly to an element in headerTemplate or footerTemplate, then reserve enough top and bottom margin for the template’s height.
The reliable configuration
Puppeteer generates PDFs using the print CSS media type. Print rendering can alter colors, and background graphics are disabled unless you request them. The following configuration addresses both behaviors:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(`
<!doctype html>
<html>
<head>
<style>
body {
font-family: Arial, sans-serif;
margin: 0;
padding: 24px;
}
h1 { margin-top: 0; }
</style>
</head>
<body>
<h1>Quarterly report</h1>
<p>The page content appears between the colored header and footer.</p>
</body>
</html>
`, { waitUntil: 'load' });
await page.pdf({
path: 'report.pdf',
format: 'A4',
displayHeaderFooter: true,
printBackground: true,
margin: {
top: '64px',
bottom: '64px',
left: '32px',
right: '32px'
},
headerTemplate: `
<style>
html { -webkit-print-color-adjust: exact; }
.bar {
width: 100%;
box-sizing: border-box;
background-color: #2457a7;
color: #ffffff;
padding: 8px 12px;
font-size: 11px;
}
</style>
<div class="bar">Quarterly report</div>
`,
footerTemplate: `
<style>
html { -webkit-print-color-adjust: exact; }
</style>
<div style="width:100%; box-sizing:border-box; background-color:#2457a7; color:#ffffff; padding:8px 12px; font-size:10px; text-align:center;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>
`
});
await browser.close();
})();The important pieces are independent settings:
| Setting | What it controls | Default or requirement |
|---|---|---|
displayHeaderFooter |
Whether Puppeteer emits the selected header and footer templates | false by default; set it to true |
headerTemplate / footerTemplate |
HTML rendered in the page header and footer areas | Put the colored element in the template itself |
printBackground |
Whether background graphics are printed | false by default; set it to true |
-webkit-print-color-adjust: exact |
Requests exact color rendering under print CSS | Place it in a <style> block inside each template |
margin.top / margin.bottom |
Space reserved for the templates | Choose values that accommodate the actual template height |
Why a page stylesheet alone does not fix the color
Page.pdf() switches the document to print media. Browsers may modify colors for print output, so a background that looks correct in a screen preview can be lightened or removed in the PDF. Puppeteer documents -webkit-print-color-adjust as the mechanism for forcing exact colors.
Header and footer templates are separate HTML fragments. A practical workaround reported in the Puppeteer issue titled “cannot add background-color to Header/Footer” is to put the print-color rule inside the template rather than relying only on the page’s main stylesheet. Treat that report as a community workaround: behavior can vary with the Puppeteer and bundled Chromium versions you install.
#1 Best Overall
- 1 ream (500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
printBackground: true is still necessary because it enables printing background graphics globally. Keep both controls in place: the PDF option enables background painting, while the template rule requests the specified color during print rendering.
Build the header and footer templates correctly
Color the template element, not the page body
Assign background-color directly to a div (or another element) inside headerTemplate or footerTemplate. Give it an explicit width and use box-sizing: border-box when padding should remain within that width.
headerTemplate: `
<style>
html { -webkit-print-color-adjust: exact; }
</style>
<div style="width:100%; background-color:#0f766e; color:white; padding:10px;">
Status report
</div>
`Reserve enough margin
The margin is not a universal constant. A template with 8-pixel padding and 11-pixel text needs less room than a two-line banner. If the margin is too small, the header or footer can be clipped or overlap the document content. Increase margin.top and margin.bottom until the complete element fits, then inspect several pages of the generated PDF.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use the supported dynamic classes
Puppeteer supports special classes in these HTML templates, including date, title, url, pageNumber, and totalPages. For example:
Rank #2
- HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America. Each ream is wrapped in a polyurethane coated paper wrapper to protect the cut sheets from moisture damage
- Sheet size – 8.5 x 11; Thickness – 20 pounds; Brightness – 92 bright white
- HP Copy&Print20 20 pounds printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design)
- All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment; 100% satisfaction guaranteed; ColorLok technology provides more vivid colors, bolder blacks and faster drying
- Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office; HP Copy&Print20 print and copy paper prevents yellowing over time to ensure a long-lasting appearance for added archival quality
footerTemplate: `
<style>
html { -webkit-print-color-adjust: exact; }
</style>
<div style="width:100%; background-color:#1d4ed8; color:white; padding:8px; text-align:right;">
<span class="pageNumber"></span>/<span class="totalPages"></span>
</div>
`These classes belong in the template HTML. Do not assume a page-content stylesheet will style the fragment in the same way.
Options you can combine with colored templates
Paper size and orientation
Set format (such as A4 or Letter) or provide a custom width and height. Landscape pages change the available width, so check that a full-width bar and its padding still fit.
Margins and bleed-like designs
Headers and footers occupy the reserved margin areas. If you want a color strip aligned with the document edges, make the template width 100 percent and tune the left and right page margins. The API does not prescribe one correct margin value; it depends on font size, padding, line height, and whether the template wraps.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #3
- 3 ream case (1,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Template text and contrast
Set the text color explicitly, especially on dark backgrounds. A background can render correctly while inherited text becomes unreadable. Keep the template compact; long text can increase its height and require larger margins.
Step-by-step troubleshooting
- Verify the switch: confirm
displayHeaderFooter: trueis in the samepage.pdf()call as the templates. - Verify placement: make sure the colored element is inside the chosen
headerTemplateorfooterTemplate, not only in the page’s body HTML. - Enable backgrounds: add
printBackground: true. Its default is false. - Request exact print colors: add
html { -webkit-print-color-adjust: exact; }in a style block inside each template. - Check the CSS declaration: use a concrete
background-colorvalue such as#2457a7on the template element itself. Check for malformed HTML or a later rule that overrides it. - Increase the reserved space: raise the top or bottom margin if the bar is clipped, missing, or colliding with body text.
- Inspect the generated PDF: test more than the first page, because page-number content, wrapping, and a different final-page layout can expose a sizing problem.
- Check versions: record the installed Puppeteer version and its bundled Chromium version if output differs between machines. Version differences are a reasonable place to investigate when the same template behaves differently.
Common symptoms and precise fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No header or footer appears | displayHeaderFooter is omitted or false |
Set displayHeaderFooter: true and provide the appropriate template |
| Text appears but the background is white | Background graphics are disabled or print color adjustment changed the color | Use printBackground: true and add the exact-color rule inside the template |
| Color is present but the bar is cut off | Top or bottom margin is shorter than the template | Increase the corresponding margin and retest |
| Body content has color but the footer does not | The color was defined only in the page content stylesheet | Set background-color directly on an element in footerTemplate |
| Page numbers are blank | The documented special class is missing or misspelled | Use <span class="pageNumber"></span> and totalPages exactly |
Performance, reliability, and maintenance
- Keep templates self-contained. Inline the small style block and the background declaration so template rendering does not depend on page-content CSS.
- Use deterministic dimensions. Explicit padding, font size, line height, and width make margin tuning repeatable across documents.
- Validate representative documents. Test short and long content, single- and multi-page output, and both portrait and landscape layouts when your application supports them.
- Pin and record runtime versions. Puppeteer controls a Chromium build, and output changes should be investigated against those versions when deployments are not identical.
- Inspect PDFs as files. A browser preview of the HTML is not proof that print CSS and PDF options are configured correctly.
Or skip the browser setup
If your actual goal is to produce a clean screenshot or PDF of a web page rather than maintain a Puppeteer runtime, ScreenshotNeo provides a single-request API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For the full parameter reference, see the ScreenshotNeo documentation.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)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}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Its 63 options include full-page capture with lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user-agent and authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage data, and an OpenAPI specification. Parameter names used by other screenshot APIs are accepted to ease migration.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated 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 matchRank #4
- 5 ream case (2,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
| Plan | Included shots | Price |
|---|---|---|
| Free | 1,000 per month | $0; no card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Yearly billing gives two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to start with 1,000 screenshots a month and no card.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Can I define the color with a CSS variable?
You can, but the template must still resolve the variable within its own HTML and CSS. For the least ambiguous output, use a concrete color declaration directly on the template element while diagnosing print-color issues.
Does printBackground replace -webkit-print-color-adjust?
No. The PDF option enables background graphics, while the CSS property requests exact print colors. Use both when a header or footer background must match the specified value.
Best Value
- 8 ream case (4,000 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
Why should I test more than one page?
Footer content such as page numbers can change its rendered width, and body content can expose margin or clipping problems only on later pages. A multi-page PDF is a better check than a single-page sample.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesFrequently Asked Questions
Can I define the color with a CSS variable?
You can, but the template must still resolve the variable within its own HTML and CSS. For the least ambiguous output, use a concrete color declaration directly on the template element while diagnosing print-color issues.
Does printBackground replace -webkit-print-color-adjust?
No. The PDF option enables background graphics, while the CSS property requests exact print colors. Use both when a header or footer background must match the specified value.
Why should I test more than one page?
Footer content such as page numbers can change its rendered width, and body content can expose margin or clipping problems only on later pages. A multi-page PDF is a better check than a single-page sample.
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
