How it renders / options.header_html and options.footer_html
Add a header, footer and page numbers to a PDF
Small HTML fragments repeated on every page, with substitution tokens for the page number, the total, the date, the title and the URL.
What it is for
This is the practical answer to page numbers. The CSS Paged Media specification defines margin boxes, meaning @top-center and its fifteen siblings, and browser engines do not implement them, so a document that uses them gets nothing at all. Header and footer fragments are how the same result is reached in a browser-based render.
The request
Sent to options.header_html and options.footer_html. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"footer_html": "<div style=\"font-size:8pt;width:100%;text-align:center;color:#666\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
"header_html": "<div style=\"font-size:8pt;width:100%;padding:0 16mm;color:#666\"><span class=\"title\"></span></div>"
}
}The actual limits
Read from the implementation rather than remembered, so these are the numbers the API enforces rather than the ones a roadmap intends.
- Five class names are substituted at render time: pageNumber, totalPages, date, title and url. An element carrying one of those classes has its content replaced.
- Setting a header widens the top margin from 1cm to 2cm automatically, and a footer widens the bottom the same way, but only when the margin was still at the default.
- The fragments do not inherit the document's stylesheet. Styles have to be inline, and the default font size is very small, so it has to be set explicitly.
- Either fragment may be sent alone. The other is filled with an empty element.
What failure looks like
The most common outcome first time is a header that does not appear. Almost always the margin is too small to hold it: if the margin was set explicitly to something under about 15mm, the automatic widening does not apply and the header is drawn outside the visible area.
When this is the wrong tool
When the running content needs to change between sections, such as a header naming the current chapter. These fragments are the same on every page. Chapter-aware running headers are what the CSS margin boxes were designed for, and they need a dedicated print engine rather than a browser-based render.
Frequently asked
Is running headers and footers available on the free plan?
Yes. There is no plan gate on this one: it behaves the same on the free plan as on every paid plan, and the only limit that applies is the monthly document allowance.
Where do these numbers come from?
The running implementation. Every figure on this page, from payload ceilings to per-plan limits, is what the API enforces today rather than what a specification says it should. If one of them is wrong, the API is the thing to believe.
Related capabilities
Options that come up in the same request, and one from each of the other groups.
Print background colours and images in a PDF
Controls whether background colours and images survive into the PDF. On by default here, which is the opposite of a browser's own default.
Render a PDF using screen CSS instead of print CSS
Chooses which CSS media type the document is rendered under: print by default, or screen when you want the page to look like the page.
Use a PDF rendering preset
Three named bundles of options for the three shapes most documents fall into, with anything you pass explicitly overriding them.
Render an HTML string to PDF over an API
Send a complete HTML document in the request body and get the PDF bytes back in the response.
Set the PDF page size in an API request
Six named paper sizes, passed in the request options, with A4 as the default when nothing is given.
Render many PDFs in one API call
Up to several hundred documents in one request, each stored and returned as a link, with per-item success or failure rather than one all-or-nothing result.
Password protect a generated PDF
Encrypts the output so a reader is asked for a password before the document opens.
Check API usage and remaining document quota
How many documents have been used this billing period, what the limit is, and what the plans are, all readable from the API rather than from a dashboard.
Everything the API does
The full list, grouped by which part of the request it belongs to.
API reference
The complete parameter documentation, including the parts with nothing interesting to say about them.
100 free documents a month, and a playground that runs a real render without a key.