Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For a header or footer repeated on every PDF page, enable Puppeteer’s displayHeaderFooter option and supply headerTemplate or footerTemplate. For content that changes between left- and right-hand pages, use CSS @page :left and @page :right margin boxes in Chrome 131 or newer. Arbitrary chapter-by-chapter running headers are a different problem: Chromium’s documented support for CSS string-set and string() has a known bug, so do not rely on it without checking your exact browser build.

Choose the kind of variation you need

“Different headers and footers” can mean several things. Puppeteer’s PDF templates handle document-wide repeated furniture, such as a report title and a changing page count. CSS page margin boxes can vary content by page side. Neither approach should be assumed to generate arbitrary, dynamically changing chapter titles on each page.

Requirement Use Key qualification
Same header/footer on every page, with page number or total pages Puppeteer headerTemplate and footerTemplate Enable displayHeaderFooter, which defaults to false.
Different content on left and right pages CSS @page :left and @page :right margin boxes Chrome supports CSS margin-box content from Chrome 131.
Running heading that changes to the current chapter title Do not assume CSS string-set/string() will work in Chromium Chrome’s guide identifies a Chromium bug; use a verified pagination design if this is essential.

The right solution depends on whether the content repeats globally, changes by page side, or must follow document structure. Confirm the Chrome version bundled with the Puppeteer package you deploy, since browser capabilities are version-sensitive.

Set a repeated header or footer with Puppeteer

Page.pdf() accepts template strings and special classes for values such as the current page number. Set sufficient top and bottom margins so the template has space and does not collide with the document body.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Adobe Acrobat Pro | PDF Software | Convert, Edit, E-Sign, Protect | PC/Mac Online Code | Activation Required
  • 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.

Minimal JavaScript example

This example shows the documented option names and special classes. Its exact appearance depends on the rendered document, page size, and installed Puppeteer/Chrome versions, so inspect your resulting PDF.

const pdf = await page.pdf({
  displayHeaderFooter: true,
  headerTemplate: '<div style="font-size:9px; width:100%; text-align:center">Report</div>',
  footerTemplate: '<div style="font-size:9px; width:100%; text-align:center"><span class="pageNumber"></span> / <span class="totalPages"></span></div>',
  margin: { top: '60px', bottom: '60px' },
});

The pageNumber span is replaced with the current page number; totalPages is replaced with the total page count. Other documented template classes are date, title, and url. Use ordinary HTML and inline styles for template presentation; make sure the template’s height fits within the reserved margin.

Complete runnable example

Save as make-pdf.js in a project where Puppeteer is installed, then run node make-pdf.js. Replace the example URL with a page you are authorized to capture.

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: 'report.pdf',
      format: 'Letter',
      displayHeaderFooter: true,
      headerTemplate: '<div style="font-size:9px;width:100%;text-align:center">Example report</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', right: '40px', bottom: '60px', left: '40px' },
    });
  } finally {
    await browser.close();
  }
})();

This example uses Puppeteer’s documented API, not a claim of a tested output. If your HTML is a local file or constructed document rather than a remote page, use the appropriate page-loading method in your application and retain the same PDF options.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #2
Acrobat Pro | 1-Month Subscription | PDF Software |Convert, Edit, E-Sign, Protect |Activation Required [PC/Mac Online Code]
  • 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.

Vary content between left and right pages with CSS

Chrome 131 and later supports generated content in CSS @page margin boxes. Use page-side selectors to place different content at the margins of left and right pages. This is a CSS printing feature, not a replacement for Puppeteer’s repeated HTML templates in every use case.

@page {
  margin: 24mm 18mm;
}

@page :right {
  @top-right {
    content: "Right-hand page";
  }
  @bottom-right {
    content: counter(page);
  }
}

@page :left {
  @top-left {
    content: "Left-hand page";
  }
  @bottom-left {
    content: counter(page);
  }
}

Include this CSS in the document being printed. The available margin-box positions include top and bottom edges; the example uses the right side on right-hand pages and the left side on left-hand pages. CSS page counters can provide page numbering. Rachel Andrew’s Chrome for Developers guide says this margin-box content is available from Chrome 131: Add content to the margins of web pages when printed using CSS.

Coordinate CSS page size and Puppeteer options

Puppeteer’s preferCSSPageSize option determines whether a CSS @page size takes priority over Puppeteer’s width, height, or format settings. It defaults to false; in that mode, the document is scaled to fit the paper dimensions specified through Puppeteer. Set preferCSSPageSize: true when the CSS page size should control the output. The documented default format is Letter.

Puppeteer’s margin is undefined by default, meaning no margins are set by that option. When you use margin boxes or header/footer templates, set margins intentionally and leave enough room for their content. A page-size mismatch or insufficient margin can cause scaling, clipping, or overlap.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
PDF Extra Lifetime - Professional PDF Editor - Best Adobe Acrobat Pro Alternative - Lifetime License for Windows PC
  • 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

Understand print media and color behavior

Puppeteer’s Page.pdf() generates output using the print media type. As a result, print-specific CSS may hide, restyle, or rearrange content compared with the browser’s screen view. If you need screen media instead, call page.emulateMediaType('screen') before PDF generation. Puppeteer also notes that print output may adjust colors; use -webkit-print-color-adjust when exact colors matter. See the Puppeteer Page.pdf() documentation and its PDFOptions interface for the current API details.

Handle chapter-specific running headers carefully

A running header that automatically displays the title of the section currently occupying a page sounds like a page-margin-box task, but it requires the browser to carry document content into generated page-margin content. Chrome’s guide identifies a Chromium bug for CSS string-set and string(). Do not promise this behavior based only on the existence of those CSS properties.

If the requirement is truly bespoke content on each logical page, consider a deliberately paginated document design or another pagination engine, then verify its output in the environment you will ship. The sources here do not establish or endorse a particular alternative engine. For a fixed, known document layout, explicit page sections and a controlled pagination workflow may be more predictable than hoping an unsupported running-title feature behaves correctly.

Validate the PDF you actually deploy

PDF layout depends on the document, CSS, page settings, Puppeteer version, and bundled Chrome version. A successful call to page.pdf() does not prove that headers fit or that every page side is correct. Render representative documents with the exact versions used in production and inspect the output.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
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]
  • 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.
  • Check the first, middle, and final pages for clipping and body-content overlap.
  • For left/right rules, inspect both page sides, including documents with an odd number of pages.
  • Verify that pageNumber and totalPages render as intended.
  • Test a short document and a long one; additional page breaks can expose layout issues that a one-page sample cannot.
  • Check page size, margins, print styles, and color output against the final PDF rather than only the browser preview.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshooting common problems

No header or footer appears

Confirm that displayHeaderFooter: true is set. Its default is false. Also confirm the relevant template string is nonempty and that you are inspecting the PDF output rather than the page’s screen rendering.

The header overlaps the page content

Increase the top margin for a header or bottom margin for a footer. Keep the template’s content height within that reserved area, and review the page at the actual output size.

Page-side CSS has no effect

Check that the Chrome version actually used by Puppeteer is at least 131 and that the CSS is included in the document printed to PDF. Confirm that your page margins leave room for margin-box content.

The PDF looks different from the web page

Page.pdf() uses print media by default. Inspect print-specific styles; call page.emulateMediaType('screen') before generating the PDF only if screen media is what you need. If colors are altered and exact colors are important, apply -webkit-print-color-adjust as appropriate.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Best Value
PDF Director 3 PLUS - Edit, Convert, Redact, Protect PDFs, Fill Forms for Win 11, 10, 8.1, 7
  • 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

The CSS page size is ignored or the page is scaled

Review preferCSSPageSize alongside format, width, or height. CSS page size takes priority when preferCSSPageSize is true; otherwise Puppeteer’s paper dimensions govern and the content is scaled to fit.

Chapter titles do not update in the margin

Do not assume CSS string-set and string() provide dynamic running titles in Chromium: Chrome’s guide flags a Chromium bug. Verify the target build or choose a pagination strategy that you have confirmed works for the document.

Or skip the browser setup

If the task is to capture a web page as an image or PDF rather than to programmatically design custom per-page headers and footers, ScreenshotNeo offers a one-request screenshot API. It does not replace Puppeteer’s PDF template or page-side CSS controls for custom PDF furniture.

Example using cURL (see the ScreenshotNeo API documentation):

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo free.

Frequently Asked Questions

Which Puppeteer template classes can insert built-in values?

The documented classes are date, title, url, pageNumber, and totalPages.

What Chrome version introduced CSS page margin-box content?

Chrome 131.

Can CSS margin boxes reliably show the current chapter title in Chromium?

Do not assume so. Chrome’s guide identifies a Chromium bug affecting string-set and string().

Quick Recap

Bestseller No. 1
Adobe Acrobat Pro | PDF Software | Convert, Edit, E-Sign, Protect | PC/Mac Online Code | Activation Required
Adobe Acrobat Pro | PDF Software | Convert, Edit, E-Sign, Protect | PC/Mac Online Code | Activation Required
Edit text and images without jumping to another app.; Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
$239.88
Bestseller No. 2
Acrobat Pro | 1-Month Subscription | PDF Software |Convert, Edit, E-Sign, Protect |Activation Required [PC/Mac Online Code]
Acrobat Pro | 1-Month Subscription | PDF Software |Convert, Edit, E-Sign, Protect |Activation Required [PC/Mac Online Code]
Edit text and images without jumping to another app.; Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
$29.99
Bestseller No. 3
PDF Extra Lifetime - Professional PDF Editor - Best Adobe Acrobat Pro Alternative - Lifetime License for Windows PC
PDF Extra Lifetime - Professional PDF Editor - Best Adobe Acrobat Pro Alternative - Lifetime License for Windows PC
Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.; EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
$99.99
Bestseller No. 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]
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]
READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.; CREATE, COMBINE, SCAN and COMPRESS PDFs
$99.99
Bestseller No. 5
PDF Director 3 PLUS - Edit, Convert, Redact, Protect PDFs, Fill Forms for Win 11, 10, 8.1, 7
PDF Director 3 PLUS - Edit, Convert, Redact, Protect PDFs, Fill Forms for Win 11, 10, 8.1, 7
Full-featured PDF Editor: Edit text in the document; Fully convert PDF to Word and Excel and continue editing
$29.99

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.