Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Puppeteer’s PDF print template, not a heading in your document body, when a header must appear on every page. Set displayHeaderFooter: true, provide headerTemplate, and reserve space with a sufficiently large margin.top. The same mechanism handles repeated footers and page counters.
Working example: a repeated header and page-number footer
This complete Node.js example loads HTML, enables Chromium’s print header area, and writes an A4 PDF. The template uses inline CSS so its appearance is predictable in print output.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
const page = await browser.newPage();
const html = `
<html>
<head>
<style>
body { font-family: Arial, sans-serif; line-height: 1.45; }
h1 { break-before: page; }
table { width: 100%; border-collapse: collapse; }
td, th { border: 1px solid #bbb; padding: 6px; }
</style>
</head>
<body>
<h1>Quarterly report</h1>
<p>Your content can span many pages.</p>
</body>
</html>`;
await page.setContent(html, { waitUntil: 'networkidle0' });
await page.pdf({
path: 'report.pdf',
format: 'A4',
displayHeaderFooter: true,
headerTemplate: `
<div style="width:100%; text-align:center; font-size:9px; color:#555;">
Acme Report
</div>`,
footerTemplate: `
<div style="width:100%; text-align:center; font-size:9px; color:#555;">
<span class="pageNumber"></span> / <span class="totalPages"></span>
</div>`,
margin: {
top: '60px',
bottom: '45px',
left: '30px',
right: '30px'
},
});
await browser.close();Install Puppeteer with npm install puppeteer, save the file as an ES module (for example, use "type": "module" in package.json), and run it with Node.js. The result is report.pdf with the header and footer repeated on each printed page.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Why a body heading appears only once
An ordinary <header> element belongs to the HTML document flow. It is laid out once, then the document is fragmented across pages; it is not automatically cloned into each fragment. Puppeteer’s headerTemplate is different: Chromium places it in the print header area whenever it creates a PDF page. That is why the API template, rather than a body element, is the reliable solution for repetition.
#1 Best Overall
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
The template is outside the body’s content box. The top margin is the reserved page geometry between the paper edge and body content. If it is too small, body text can run into the header or the header can be clipped. Reserve comparable space at the bottom when using footerTemplate.
Template HTML and dynamic values
Supported replacement classes
Chromium replaces these documented classes when rendering a PDF:
date— print date.title— document title.url— page URL.pageNumber— current page number.totalPages— total page count.
For example, a right-aligned footer can contain <span class="pageNumber"></span> of <span class="totalPages"></span>. Use these classes instead of trying to calculate page totals in JavaScript; pagination is finalized by Chromium.
Keep templates self-contained
Use valid, small HTML and inline styles. Do not assume your page stylesheet, web fonts, or framework classes are available in the print margin area. A simple div with explicit width, font size, alignment, and color is less likely to render differently after a Chromium upgrade. If you need a logo, use a data URL or ensure the resource is available before PDF generation.
Print media, colors, and page geometry
Print versus screen CSS
page.pdf() generates output with the print CSS media type. Rules inside @media print apply by default, while screen-only rules may not. If your design intentionally targets the screen, switch before generating the file:
Rank #2
![Acrobat Pro | 1-Month Subscription | PDF Software |Convert, Edit, E-Sign, Protect |Activation Required [PC/Mac Online Code]](https://m.media-amazon.com/images/I/41CUq+X3jVL._SL160_.jpg)
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
await page.emulateMediaType('screen');
await page.pdf({
path: 'screen-styled.pdf',
displayHeaderFooter: true,
headerTemplate: '<div style="font-size:9px">Report</div>',
margin: { top: '50px' }
});Choose one media strategy deliberately. Changing it can alter line wrapping and therefore the number of pages.
Preserving background colors
Print output modifies colors by default. Add -webkit-print-color-adjust: exact to the relevant print styles when exact color reproduction matters, and set printBackground: true in the PDF options when backgrounds must be included.
Paper size and scaling
Use format: 'A4' or format: 'Letter' for standard paper. For a custom sheet, specify width and height. If your stylesheet contains an @page size, set preferCSSPageSize: true so that CSS takes priority over API dimensions.
scale accepts values from 0.1 to 2. Scaling changes both readable size and pagination, so recheck header clearance after changing it. pageRanges can restrict output to selected pages, such as '1-3'. Use landscape: true for wide reports when the selected format supports it.
Controlling layout across page breaks
- Inspect a multi-page output whenever you change font, width, margin, or scale; a one-line wrap can move an entire section.
- Use print CSS such as
break-before,break-after, andbreak-insideto control sections and table rows. - Tables with long rows can split awkwardly. Set print-specific widths and avoid placing essential content in a row that cannot fit in the remaining space.
- Do not reserve header space by adding a large body padding value; that shifts content on the first page but does not correctly define the repeating print area.
CSS margin boxes: a newer alternative
Chromium 131 introduced generated content in print margin boxes. With an @page rule, constructs such as @bottom-right { content: counter(page); } can place a page counter in the margin, and the pages counter represents the total. This is dependent on the Chromium version bundled or configured in your deployment. For applications that need the documented Puppeteer API behavior across environments, headerTemplate and footerTemplate remain the more portable choice.
Rank #3
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
Useful options in one configuration
await page.pdf({
path: 'controlled.pdf',
format: 'A4',
landscape: false,
displayHeaderFooter: true,
headerTemplate: '<div style="width:100%;font-size:9px;text-align:left">Internal</div>',
footerTemplate: '<div style="width:100%;font-size:9px;text-align:right">Page <span class="pageNumber"></span> of <span class="totalPages"></span></div>',
printBackground: true,
preferCSSPageSize: true,
pageRanges: '1-10',
scale: 1,
margin: { top: '55px', bottom: '40px', left: '24px', right: '24px' }
});Do not combine conflicting sizing assumptions casually: format, explicit dimensions, CSS @page, and preferCSSPageSize determine the paper geometry, while margins determine the usable content area.
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 glitchesTroubleshooting repeated headers
The header is missing everywhere
Check that displayHeaderFooter: true is present in the same page.pdf() call. It defaults to false.
The header is clipped or overlaps text
Increase margin.top and render a document with several pages. The margin must be large enough for the template’s line height, padding, and any logo. Increase margin.bottom similarly for a footer.
The page number is blank
Use the exact class names, including capitalization: pageNumber and totalPages. They are replacement markers, not values you set yourself.
Styles or images do not appear
Move critical CSS inline in the template, verify that external resources are reachable before calling page.pdf(), and wait for the page’s required assets. A template that depends on the document’s stylesheet is especially fragile.
Recommended Free Tools
Rank #4
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
Colors or layout differ from the browser view
Remember that print media is the default. Decide whether to call emulateMediaType('screen'), enable printBackground, and apply -webkit-print-color-adjust: exact where needed.
CSS page sizing is ignored
Set preferCSSPageSize: true and verify the Chromium version in the runtime supports the CSS you rely on. Also check that no API format, width, or height assumption contradicts the stylesheet.
Operational and cost considerations
Launch and close the browser deterministically, preferably in a try/finally block in a server process. Reuse a browser instance for multiple jobs when safe, but create an isolated page per document. Set explicit navigation and asset timeouts, and log the HTML URL, PDF options, and Chromium version for reproducibility. For large reports, wait for fonts and images before printing; otherwise pagination may change after resources finish loading.
Puppeteer itself does not provide a hosted screenshot or PDF quota. Your costs are the compute, memory, storage, and operational work of running Chromium. A managed capture API can be preferable when you do not want to maintain browser processes, consent handling, or retry logic.
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. Its PDF endpoint can capture a URL without you provisioning Puppeteer:
Best Value
- Full-featured PDF Editor: Edit text in the document
- Fully convert PDF to Word and Excel and continue editing
- NEW: Further development of existing functions
- NEW: Even faster and more user-friendly
- NEW: Over 75 small improvements in all areas
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 documentation for PDF parameters and output settings. Before capture, it accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account to try 1,000 screenshots a month without adding a card.
FAQ
Can I put a different header on the first page?
Use CSS page-break structure or generate separate PDFs for different sections. A single headerTemplate is applied to the print header area for every page in that PDF.
Free tools Windows power users keep installed
One-click scans. No signup required.
Can the template contain arbitrary JavaScript?
Treat it as a small HTML fragment with inline styles and documented replacement classes. Put application logic in the page before calling page.pdf(), not in the margin template.
Why did adding a header increase the page count?
The reserved top and bottom margins reduce the body’s usable height. That can create additional page breaks, which is expected; adjust margins, typography, or paper size only if the resulting layout is acceptable.
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.
