Put the image markup in Puppeteer’s PDFOptions.headerTemplate and set displayHeaderFooter: true. The header is HTML, but Puppeteer’s documented PDF options do not specify which image source formats work in that template or promise that image requests finish before the PDF is generated. Treat the image source as something to verify in your runtime: generate the PDF, inspect it, and do not assume that a filesystem path or remote URL will work just because it appears in the HTML.
What Puppeteer documents about PDF headers
Puppeteer’s Page.pdf() method creates a PDF using the print CSS media type. Its PDF options include headerTemplate, an HTML template for the header, and displayHeaderFooter, which enables visible headers and footers. You need both the template and the display setting for a custom header to appear.
The API also documents a small set of special classes that can be placed in the template: .date, .title, .url, .pageNumber, and .totalPages. These insert the print date, document title, URL, current page number, and page count, respectively. They are separate from image loading; their availability does not establish how an image in the template is fetched or when it is ready.
The PDF options reference describes waitForFonts as waiting for document.fonts.ready and gives it a documented default of true. That setting concerns fonts. It is not a documented way to wait for images in a header template.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Add the image to headerTemplate
The basic implementation is to include an <img> element in the header HTML string. Give it explicit dimensions so the intended space is clear, and use a source that your Puppeteer browser can access. For example, the following uses a remote HTTPS image URL supplied through an environment variable. It demonstrates the API shape, not a guarantee that a remote image will load in every Puppeteer environment.
import puppeteer from 'puppeteer';
const imageUrl = process.env.HEADER_IMAGE_URL;
if (!imageUrl) {
throw new Error('Set HEADER_IMAGE_URL to an image URL accessible to Chromium.');
}
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setContent('<main><h1>Example report</h1><p>PDF content goes here.</p></main>');
const headerTemplate = `
<div style="width:100%; font-size:9px; padding:0 24px; display:flex; align-items:center; justify-content:space-between;">
<img src="${imageUrl}" style="width:120px; height:32px; object-fit:contain;" />
<span>Example report</span>
</div>`;
await page.pdf({
path: 'output.pdf',
format: 'A4',
displayHeaderFooter: true,
headerTemplate,
footerTemplate: '<div style="width:100%; text-align:center; font-size:8px;"><span class="pageNumber"></span> / <span class="totalPages"></span></div>',
margin: { top: '70px', right: '24px', bottom: '50px', left: '24px' }
});
} finally {
await browser.close();
}Install Puppeteer in your Node.js project before running the example, then set HEADER_IMAGE_URL to the candidate image URL and execute the file as an ES module. The official Puppeteer guide’s basic flow is to launch the browser, create a page, navigate to or set page content, and call page.pdf(). Page.setContent() is a documented way to set the page’s HTML. Adapt the main content and image source to your application, then verify the generated PDF.
The exact image behavior is not established by the documented options described here. In particular, this example should not be read as a promise that remote URLs, local paths, data URLs, or any other source form is universally supported in a header template. Test the source form and runtime you actually deploy. If the image is missing, the result—not the presence of an <img> tag in the string—is the deciding check.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Make the header fit the printed page
A header can be present but clipped, crowded, or too close to the page content. Set the PDF margins deliberately and reserve enough top margin for the header. The example uses a 70-pixel top margin; that is an illustrative layout choice, not a universal size. Adjust it to the image height, padding, paper size, and content.
- Paper format: choose a format such as
A4or set the page size using the PDF options supported by your Puppeteer version. - Margins: use
marginto reserve room for the header and footer. Check the top and bottom on pages with both elements enabled. - Print CSS:
Page.pdf()renders with print media. Layout rules that differ under print CSS can affect the document area around the header. - Color: Puppeteer’s PDF reference notes that colors are modified for printing by default. If your header relies on exact colors, inspect the output rather than assuming screen rendering and print rendering match.
- CSS page size: the
preferCSSPageSizeoption is available when print CSS should control the paper size. Decide whether the stylesheet or PDF options should govern the page dimensions, then check the result.
Keep the image’s CSS dimensions modest and explicit. If you set a header taller than the top margin can accommodate, the document’s layout may not look as intended even if the image itself loads.
Verify image loading instead of assuming it
Puppeteer’s PDF reference documents the header template as HTML but does not specify image-source rules or an image-wait guarantee for it. For that reason, a successful call to page.pdf() does not by itself prove that the header image appeared. Inspect the generated PDF, including pages beyond the first if the header repeats, and check that the image is not clipped or missing.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
- Run the PDF generation in the same kind of environment used in deployment, including the same network access and image host.
- Open the resulting PDF and confirm that the image is visible, has the expected proportions, and appears on pages where the header should repeat.
- Change one variable at a time—source accessibility, dimensions, or margins—and regenerate. This separates image retrieval problems from layout problems.
- Keep
waitForFontsin perspective: its documented purpose is font readiness, not image readiness.
If you need to investigate browser-side image loading, you can separately test whether the page that produces the PDF can load the candidate image. That is useful evidence about access to the resource, but it does not establish that the separate header-template rendering path loads or waits for that image identically. The final PDF remains the check that matters.
Use the documented template classes when they help
The header and footer templates can contain the documented classes for dynamic print values. For instance, a footer can place <span class="pageNumber"></span> next to <span class="totalPages"></span> to show the current page and page count, as in the code above. The other documented classes are .date, .title, and .url. Use only the values you need; a header with an image and title does not need page-number markup unless that information belongs there.
These classes are a template feature, not a substitute for testing image behavior. An image can fail while dynamic text works, or fit correctly while the document content collides with the reserved header area.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Troubleshoot a missing or misplaced image
The header is absent
- Confirm that
displayHeaderFooter: trueis set in the options passed topage.pdf(). - Confirm that the image markup is inside the
headerTemplatestring actually passed to that call. - Check the generated file again after confirming the options, rather than judging from the regular page viewport.
The header appears but the image does not
- Check that the image URL is accessible from the browser process in the deployed environment. A URL reachable from your laptop may not be reachable from a container or restricted runtime.
- Check the URL and the image host’s response independently. Then regenerate and inspect the PDF; availability in a separate browser test is not a documented guarantee for header-template rendering.
- Do not treat
waitForFontsas an image wait option. The documented behavior is to wait fordocument.fonts.ready. - Try a source form only after testing it in your own Puppeteer version and runtime. The documented API information here does not establish that any particular image source form is guaranteed.
The image is clipped or crowds the content
- Reduce the image’s CSS width or height, or use
object-fit:containwhen the full image should remain visible. - Increase the top margin to create space for the header, and check the bottom margin if you also use a footer.
- Review the PDF paper format and print CSS, particularly if page sizing is controlled by both CSS and PDF options.
The image differs from the screen version
Remember that page.pdf() uses print CSS media and applies print color adjustments by default. Inspect the PDF’s actual rendering and adjust print styles or PDF options where appropriate.
Or skip the browser setup
If your goal is to capture a web page as an image rather than generate a PDF with a Puppeteer header template, ScreenshotNeo provides a website screenshot API. A single request can return PNG, JPEG, WebP, or PDF; it is an alternative capture workflow, not a way to configure a Puppeteer PDF header.
For example, save a screenshot of a page as WebP with cURL:
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
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 request details. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to try the API.
What to check before shipping
- The options passed to
page.pdf()includedisplayHeaderFooter: trueand the intendedheaderTemplate. - The image source works in the actual browser environment that generates the PDF.
- The resulting PDF visibly contains the image, with enough margin for the header and any footer.
- Print media styles, paper size, and color treatment produce the expected output.
- You have not relied on
waitForFontsas evidence that the header image loaded.
Frequently Asked Questions
Does Puppeteer officially guarantee that a remote image URL works in `headerTemplate`?
The documented PDF options described here do not specify supported image source forms or guarantee remote-image loading in header templates. Test the source in the Puppeteer runtime you deploy and inspect the generated PDF.
Does `waitForFonts: true` wait for a header image?
No such image-wait behavior is documented for that option. The reference describes it as waiting for `document.fonts.ready`.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC 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 & 11Can the header template show page numbers?
Yes. Puppeteer documents the template classes `.pageNumber` and `.totalPages` for the current page and page count; `.date`, `.title`, and `.url` are also documented.
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.
