Puppeteer Header Template

Puppeteer is powerful, but the Header Template functionality is very limiting. Learn how cloudlayer.io has solved many of the issues with our own header solution. Learn how to use Puppeteer to Render HTML with a Header Template.

Puppeteer Header Template

When working with Puppeteer, you will realize what tremendous power it has. It can render HTML exceptionally well. Since it uses the Chrome rendering engine, you get incredibly high fidelity renderings, which is why we at cloudlayer.io chose to use Puppeteer from the start. However, it also has significant limitations that can cause many people headaches when trying to do certain things using Puppeteer as opposed to WKHTML or something like PrinceXML. That is why we are busy at work augmenting Puppeteer to add these capabilities into our service.

One of the limitations that Puppeteer has is the ability to create intricate headers. Since you are using HTML, you could develop headings in your HTML and use some Print CSS media tags to try to get things looking right with some success. But you will quickly realize that it has pretty severe drawbacks. One of them is how and where the page breaks occur and how the content gets laid out.  In many circumstances, your content may get overlapped with your header and vice versa. What can make this situation even worse is that you may have this only occur on a tiny percentage of your PDF generations, making it challenging to track down the issue.

Our Solution

So how did we solve this? We created a system that allows you to define your header in your HTML.  You simply wrap your header in a div or any other HTML element, you can even include an image/logo of your choice. Then when calling our URL to PDF API endpoint you can pass in parameters for the headerTemplate.

For example, lets say your HTML looks like the following:

<!DOCTTYPE html>
    	<div class="header">
            <img src="https://example.com/logo.png"/>
            <h1>This is an example</h1>
HTML Snippet

Lets say for the sake of simplicity this page is hosted at: "https://example.com/header"

Note: This path doesn't exist, this is for illustration purposes only.

Here is an example payload you would pass into our URL to PDF endpoint:

	"url": "https://example.com/header",
	"headerTemplate": {
		"method": "extract",
		"selector": ".header",
		"margin": {
			"bottom": "10px",
            "top": "10px",
            "left": "10px",
            "right": "10px"
		"imageStyle": {
			"padding-bottom": "10px",
			"height": "48px"
		"style": {
			"width": "100%",
			"border-top": "1px solid blue",
			"border-bottom": "1px solid blue"
JSON Parameters

How it works

You may be wondering how this works? We are extracting the HTML element that you specify in the selector.  Note: This can be any selector, in our example we are using a class selector.  Since Puppeteer doesn't support external resources, everything needs to be converted to embeddable or inline formats. After extracting the HTML element from the DOM, it's sent through a custom parsing engine where this work is performed.  Images, for example are converted to embedded images, and styles are applied based on the settings specified in the parameters.

What about the "method" : "extract" parameter? What is that all about? Well, it turns out that creating headers to cover everyone scenario is complicated.  The extraction technique is the solution that was just covered. We have additional solutions that we will be adding to cover every header/footer template out there!

How do you get started?

If you are interested in testing out our service, create an account which will let you create 100 documents at no cost.  If you like our service, you can upgrade to one our affordable packages. Check out our pricing for more details.