How it renders / options.print_background
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.
What it is for
Print stylesheets historically dropped backgrounds to save ink, and browsers still default to dropping them. For a generated document that default is almost always wrong: a certificate with no background is a page of centred text, and a table with no zebra striping is harder to read. So this defaults to true.
The request
Sent to options.print_background. Everything else on this page is what happens around it.
{
"html": "<!doctype html>...",
"options": {
"print_background": true
}
}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.
- Boolean, defaulting to true.
- It governs the whole document. There is no per-element form of this option.
- The CSS equivalent, print-color-adjust: exact, is worth setting on elements whose background is load-bearing, because it survives being rendered somewhere other than here.
What failure looks like
Setting it to false and then wondering where a design went. Everything else renders, the layout is identical, and every tinted panel, dark header and coloured badge is white. It is one of the more disorienting output problems because nothing about it looks like an error.
When this is the wrong tool
When the document is going to be printed in quantity on a desktop printer and the background is decorative. A full-bleed dark header costs real toner across a thousand pages, and that is a legitimate reason to turn it off deliberately rather than to leave the browser default in place by accident.
Frequently asked
Is background graphics 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.
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.
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.
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.