If a Puppeteer or Browsershot PDF has no header or footer, the usual cause is configuration: Chrome-generated print headers and footers are disabled by default. Enable the print regions, pass a template through the API layer you are using, and leave enough top and bottom margin for the template. Direct Puppeteer uses displayHeaderFooter, headerTemplate, and footerTemplate; Spatie Browsershot v4 exposes the corresponding showBrowserHeaderAndFooter(), headerHtml(), and footerHtml() methods.
Fix the configuration first
There are two APIs involved, but they control the same Chromium PDF settings. Puppeteer passes options directly to Page.pdf(). Browsershot translates its fluent PHP methods into those options. A template alone is not enough: the display switch must also be enabled.
| Layer | Enable generated regions | Header markup | Footer markup |
|---|---|---|---|
| Puppeteer | displayHeaderFooter: true |
headerTemplate |
footerTemplate |
| Spatie Browsershot v4 | showBrowserHeaderAndFooter() |
headerHtml() |
footerHtml() |
The Puppeteer reference currently shown for this API is version 25.12.0, while the Spatie example is for Browsershot v4. Match the names and behavior to the versions installed in your project rather than assuming another release has identical details.
Direct Puppeteer: a complete PDF example
Set displayHeaderFooter to true in the same page.pdf() call that supplies the templates. The following example prints a title in the header and the current page number in the footer.
#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.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setContent(`
<!doctype html>
<html>
<body>
<h1>Quarterly report</h1>
<p>Report content goes here.</p>
</body>
</html>
`);
await page.pdf({
path: 'document.pdf',
format: 'A4',
displayHeaderFooter: true,
headerTemplate: `
<div style='font-size:9px; width:100%; text-align:center;'>
Quarterly report
</div>
`,
footerTemplate: `
<div style='font-size:9px; width:100%; text-align:center;'>
Page <span class='pageNumber'></span>
</div>
`,
margin: {
top: '20mm',
right: '10mm',
bottom: '20mm',
left: '10mm'
}
});
await browser.close();
})();The important parts are not the wording or styling: the display flag is enabled, each template is supplied through the matching option, and the page has explicit top and bottom space. If you need a total-page count, check the documentation for your installed Puppeteer and Chromium combination before relying on a totalPages class; the references consulted do not present identical placeholder lists.
Use Puppeteer’s documented template classes
Puppeteer documents special span classes for values inserted into print templates:
datefor the print datetitlefor the document titleurlfor the document locationpageNumberfor the current page number
These classes belong in the header or footer markup, for example <span class='pageNumber'></span>. The Browsershot guide also shows totalPages, but that list is not identical to the Puppeteer reference. Treat a total-page value as version-sensitive and verify it against the documentation shipped for your project.
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.
Spatie Browsershot v4: the matching fix
Browsershot wraps the same Chromium options in a PHP chain. Call showBrowserHeaderAndFooter() before saving the PDF, then provide markup with headerHtml() and footerHtml(). The documented example also sets margins so the generated regions have room.
Free tools Windows power users keep installed
One-click scans. No signup required.
<?php
use SpatieBrowsershotBrowsershot;
Browsershot::html('<h1>Quarterly report</h1><p>Report content goes here.</p>')
->showBrowserHeaderAndFooter()
->headerHtml('<div>Document title</div>')
->footerHtml('<div><span class="pageNumber"></span> / <span class="totalPages"></span></div>')
->margins(20, 10, 20, 10)
->save('document.pdf');showBrowserHeaderAndFooter() maps to displayHeaderFooter: true, headerHtml() maps to headerTemplate, and footerHtml() maps to footerTemplate. If you are reading a Puppeteer example while editing Browsershot code, translate the option names instead of passing them as if they were PHP methods.
Make room for the templates
Headers and footers are printed in reserved page regions, not inserted into the normal document flow. A template can therefore be enabled and present while appearing clipped, crowded against the body, or apparently absent because there is no useful space at the page edge. Inspect the PDF margin settings together with the page format.
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
- Increase the top margin when the header overlaps the first line of content.
- Increase the bottom margin when the footer overlaps the last line or is cut off.
- Keep the template’s own markup compact while diagnosing layout.
- Confirm that the selected paper format and orientation are the ones you intended; changing either changes the available page area.
The Browsershot guide demonstrates margins(20, 10, 20, 10). Use values appropriate for your document and verify the resulting PDF rather than assuming a margin adjustment alone explains every missing-header problem.
Understand the hide methods
Browsershot has separate methods for removing individual templates and for disabling browser-generated regions:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems| Method | Effect |
|---|---|
hideHeader() |
Replaces the header template with an empty paragraph. |
hideFooter() |
Replaces the footer template with an empty paragraph. |
hideBrowserHeaderAndFooter() |
Sets the display option to false, disabling both browser-generated regions. |
If a chain enables the regions and later calls hideBrowserHeaderAndFooter(), the later setting is the one to investigate. Likewise, an apparently empty result can come from an empty template or a hide method rather than from a Chromium rendering failure.
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.
Diagnostic sequence for a missing header or footer
- Check the switch. In direct Puppeteer code, look for
displayHeaderFooter: true. In Browsershot, look forshowBrowserHeaderAndFooter(). The Puppeteer default isfalse. - Check the interface. Puppeteer requires
headerTemplateandfooterTemplate. Browsershot requiresheaderHtml()andfooterHtml(). A correctly written template passed to the wrong layer will not configure the PDF. - Reduce the template. Replace the markup temporarily with a short text fragment and a simple inline style. This distinguishes a configuration problem from a problem in the original HTML, assets, or styling.
- Inspect margins and format. Compare the top and bottom margins with the visible size of the template. Also check paper size and orientation.
- Test placeholders independently. Start with literal text and then add
pageNumberor other documented classes. If a value does not appear, verify that placeholder against the installed version’s documentation. - Verify the generated file. Open the actual PDF produced by the failing code, not a cached or previously generated file. Confirm the output path and the timestamp while testing.
- Record versions and a minimal reproduction. Capture the Puppeteer version, Browsershot version, Chromium build, the PDF call, the template strings, margin settings, and the generated output. Without those details, a title alone cannot establish a project-specific root cause.
Common symptoms and targeted fixes
| Symptom | Likely check | Targeted action |
|---|---|---|
| Neither region appears | The display setting is still at its default. | Enable displayHeaderFooter or call showBrowserHeaderAndFooter(). |
| Body prints but custom text does not | The template was supplied through the wrong API name or not supplied at all. | Use Puppeteer’s template options or Browsershot’s HTML methods for the layer you actually call. |
| Text is clipped or overlaps content | There is insufficient top or bottom margin. | Adjust the PDF margins and re-open the resulting file. |
| Page number is blank | The class name or template is not accepted by the installed version. | Try literal text first, then verify the documented placeholder spelling and casing. |
| A previously working footer disappeared after refactoring | A hide method or a later option changed the final configuration. | Search the complete chain for hideFooter(), hideHeader(), or hideBrowserHeaderAndFooter(). |
| Only one project fails | Runtime versions, Chromium, markup, or assets differ. | Compare a minimal reproduction and record package and Chromium versions before assigning a cause. |
Template content, assets, and limits of the diagnosis
Header and footer templates are print templates, so test them separately from the document body. Keep the first reproduction to literal text and documented placeholder spans. Then add the real branding, styles, and assets one at a time. The available references do not establish a universal CSS recipe or guarantee that arbitrary HTML/CSS, external fonts, or external assets behave identically in every runtime. If adding one of those causes a failure, report the exact template, runtime versions, and output rather than treating it as a general Puppeteer rule.
Similarly, the configuration fix explains the common “nothing appears” case; it cannot identify a project-specific bug without executable code and a reproducible result. The most useful support bundle is a small HTML input, the exact Puppeteer or Browsershot call, installed package versions, Chromium version, margin and format settings, and the generated PDF or a precise description of what is missing.
Performance and reliability considerations
- Keep templates small while troubleshooting so layout changes are easy to attribute.
- Generate a fresh output for each test and inspect that file directly.
- Use the same browser executable and package versions in development and production when comparing results.
- Do not infer support for a particular font, image, or CSS feature from the existence of the template options; validate those dependencies in the runtime that creates the PDF.
- When page counts or print metadata matter, pin the versions you deploy and verify the placeholder behavior after upgrades.
Or skip the browser setup
If your requirement is a clean capture or PDF of a public page rather than a hand-built Puppeteer print pipeline, ScreenshotNeo provides a single GET request that returns PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or 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 for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for authentication and options. This example captures a page as WebP:
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.webpEquivalent Python:
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)Equivalent 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(`HTTP ${res.status}`);
const fs = require('node:fs');
fs.writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo also supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets and arbitrary viewports, retina scale, PDF paper size, margins, landscape mode and page ranges, custom CSS and JavaScript, clicks before capture, selector hiding, waits, request and resource blocking, custom headers, cookies, user agents and authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs are accepted to ease migration.
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Create a free ScreenshotNeo account to start without a card.
Frequently Asked Questions
What information should I include when reporting a header or footer failure?
Include a minimal HTML input, the exact PDF call or Browsershot chain, Puppeteer and Browsershot versions, the Chromium version, margin and format settings, and the generated PDF or a precise description of the missing content.
Recommended Free Tools
Why can two machines produce different results from the same template?
The documented options do not guarantee identical behavior for every Chromium build, font, external asset, or CSS feature. Compare the browser and package versions and remove external dependencies in a minimal reproduction before drawing a conclusion.
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.
