Recommended Free Tools
To add repeating headers or footers to a Puppeteer PDF, set displayHeaderFooter: true in page.pdf() and supply a header and/or footer HTML template. Reserve room for them with PDF margins. By default, Puppeteer prints using the print CSS media type; use preferCSSPageSize: true if the document’s CSS @page size should take precedence over PDF paper-size options.
Enable a repeating header or footer
Puppeteer’s Page.pdf() method leaves headers and footers off by default. Turn them on with displayHeaderFooter: true, then provide headerTemplate, footerTemplate, or both. Each template is HTML, and Puppeteer supplies values through special CSS classes.
date: the formatted print date.title: the document title.url: the document location.pageNumber: the current page number.totalPages: the document’s page count.
For example, a footer can combine the page number and total page count as Page <span class="pageNumber"></span> of <span class="totalPages"></span>. Use the classes as shown; they are placeholders for Puppeteer to populate. Header and footer templates can be supplied independently, so a document can have only one, both, or neither.
A complete configuration example
This example assumes you already have a Puppeteer page open and loaded with the document to print. The margins are illustrative: set them to suit the actual template height and confirm that the content and furniture fit in the generated PDF.
#1 Best Overall
await page.pdf({
path: 'document.pdf',
displayHeaderFooter: true,
headerTemplate: `
<div style="font-size: 9px; width: 100%; text-align: center;">
<span class="title"></span>
</div>`,
footerTemplate: `
<div style="font-size: 9px; width: 100%; text-align: center;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>`,
margin: { top: '60px', bottom: '60px' },
printBackground: true,
});The title class in the header displays the document title; the two footer classes display the current and total page numbers. Adjust the font, alignment, and margin values for your design rather than treating the sample dimensions as universal. Puppeteer documents the option names, template contract, classes, and defaults in its PDFOptions reference.
Make the document’s CSS match the PDF
page.pdf() uses the print CSS media type by default. Write print-specific layout rules for the PDF, and use screen emulation only when you deliberately want screen styles instead. To switch media type, call page.emulateMediaType('screen') before generating the PDF.
await page.emulateMediaType('screen');
await page.pdf({ path: 'screen-styled.pdf' });For ordinary print output, leave that call out and let Puppeteer use print media. If the page looks right in a browser tab but different in the PDF, first check whether the relevant rules are inside a print media query or whether the page was explicitly switched to screen media.
Choose which page-size declaration wins
A document can declare paper size in CSS with @page, or you can specify it through PDF options such as format, width, or height. By default, preferCSSPageSize is false: Puppeteer uses the paper option and scales the content to fit. Set it to true when the CSS page size should take priority.
Rank #2
await page.pdf({
path: 'document.pdf',
preferCSSPageSize: true,
});With CSS controlling size, a stylesheet can contain a rule such as @page { size: A4; }. With the default preference, specify the paper size in the PDF options instead. If you provide format as well as width and height, format takes priority over those dimensions. Avoid setting competing size declarations unless you have chosen which one should govern the output.
Keep page furniture inside the printable area
When margin is omitted, Puppeteer documents that no margins are set. A header or footer that has no reserved space can overlap the document content or fail to appear as intended. Set explicit top and bottom margins when the design needs room for repeating furniture, and size them against the rendered template—not just the font size. There is no universal margin value: a one-line footer and a multi-line header need different space, and the document’s own layout affects the usable area.
Backgrounds and print colors
PDF backgrounds are omitted unless you opt in with printBackground: true. Enable it when the document depends on background colors or graphics. Print rendering can also change colors; Puppeteer points to the CSS property -webkit-print-color-adjust when exact colors are needed. Check the generated PDF in the viewer and, where relevant, in the final print path: a CSS instruction does not remove the need to inspect the output.
await page.pdf({
path: 'branded-document.pdf',
printBackground: true,
});Background output and page sizing are separate concerns: enabling backgrounds does not make CSS @page authoritative, and setting page size does not turn backgrounds on.
A practical end-to-end pattern
The following example shows where the PDF options fit in a small script. It assumes Node.js and an installed Puppeteer package; it opens a page, loads a URL, and saves a PDF. Replace the URL and output path for your use. If your stylesheet should control paper size, add preferCSSPageSize: true and declare the size in @page; otherwise use a PDF paper option such as format.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.pdf({
path: 'document.pdf',
displayHeaderFooter: true,
headerTemplate: `
<div style="font-size: 9px; width: 100%; text-align: center;">
<span class="title"></span>
</div>`,
footerTemplate: `
<div style="font-size: 9px; width: 100%; text-align: center;">
Page <span class="pageNumber"></span> of <span class="totalPages"></span>
</div>`,
margin: { top: '60px', bottom: '60px' },
printBackground: true,
});
} finally {
await browser.close();
}
})();The example’s waitUntil value is one way to choose when navigation is considered complete; a page that loads content later may need an application-specific wait before printing. The exact wait condition depends on the site and should be chosen so the content you need is present without making the capture wait indefinitely.
Troubleshoot common PDF layout problems
The header or footer is missing
Check that displayHeaderFooter is explicitly true and that the corresponding template option is present. Those features are off by default. Then inspect the template HTML and confirm that the placeholder class names are exactly date, title, url, pageNumber, or totalPages, as appropriate.
The furniture overlaps the document or is clipped
Set explicit top and bottom margin values to make room for the header and footer. Increase the relevant margin if the template is taller than the reserved area, then inspect the resulting PDF. Puppeteer’s reference does not prescribe a universal margin or guarantee a particular layout for every template.
The paper size is not what the CSS declares
Check preferCSSPageSize. Its default is false, so PDF paper options control and the content is scaled to fit. Set it to true if @page should take precedence. Also check whether a supplied format is overriding width and height.
Colors or background graphics are absent
Set printBackground: true if the page needs backgrounds; they are excluded by default. If printed colors still differ, review -webkit-print-color-adjust and inspect the PDF in the intended viewer or print workflow.
The PDF uses the wrong styling mode
page.pdf() defaults to print media. Remove an unintended page.emulateMediaType('screen') call, or add it before page.pdf() if screen styling is the desired result.
A template behaves differently from the page stylesheet
The PDFOptions reference defines template HTML and substitution classes, but it does not establish that arbitrary page CSS, external stylesheets, scripts, or assets behave identically inside header and footer templates. Keep templates simple and self-contained, and validate them in the Puppeteer version and browser runtime you deploy rather than relying on undocumented behavior.
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 →Best Value
- Used Book in Good Condition
Performance, reliability, and version checks
PDF generation happens after navigation and any required application-specific waits. The end-to-end time therefore depends on both the page becoming ready and PDF rendering; a broad wait condition can hold the job up when a site keeps network activity open. Choose a readiness condition that fits the page, and avoid adding a screen-media switch or other work unless the output needs it.
For reliable layouts, treat the generated PDF as the output to verify: check page size, whether the template is visible on every page as intended, whether margins preserve the content area, and whether backgrounds and colors survive in the target viewer. The documented API page consulted here is marked Puppeteer version 25.12.0. PDF option behavior is version-sensitive, so recheck the reference when upgrading Puppeteer or changing its browser runtime.
Or skip the browser setup
If you need a clean page capture or a PDF without configuring Puppeteer, ScreenshotNeo is a website screenshot API and MCP server. It can return screenshots or PDFs, but the facts available for it do not establish custom repeating header/footer templates or CSS @page control; keep Puppeteer for those requirements. For a straightforward screenshot capture, use this one-call example; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners as a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
References
- Puppeteer, Page.pdf() method (API page marked version 25.12.0).
- Puppeteer, PDFOptions interface (API page marked version 25.12.0).
Frequently Asked Questions
Can a Puppeteer PDF have a header but no footer?
Yes. Enable displayHeaderFooter and provide only the template you need; the header and footer options are independent.
Does setting printBackground make the PDF use screen CSS?
No. It controls whether backgrounds are included. page.pdf() still uses print media unless you explicitly emulate screen media before generating the PDF.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
