The shape of the page / options.prefer_css_page_size
Use the CSS @page size instead of a format
Tells the renderer to use the page box the document declares rather than a named format, which is how every non-standard size is reached.
What it is for
The API accepts six named formats and that covers standard paper. Everything with a die, a roll or a holder behind it, meaning labels, receipts, cards, badges and tickets, needs an explicit rectangle, and the right place for that rectangle is the document's own CSS: it travels with the markup, so the size cannot be lost between the template and the call that renders it.
The request
Sent to options.prefer_css_page_size. Everything else on this page is what happens around it.
{
"html": "<!doctype html><html><head><style>@page { size: 101.6mm 152.4mm; margin: 0; }</style></head>...",
"options": {
"prefer_css_page_size": 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. When true, the size and margins declared in the document's @page rule win.
- It is the only route to a size outside the six named formats.
- Do not also pass a format. The two sources disagree and which one wins is not something the caller should have to know.
What failure looks like
If the document has no @page rule and this flag is set, the output falls back to a default page rather than erroring. That produces a correctly rendered document at the wrong size, which is the least helpful kind of failure because it looks like success.
When this is the wrong tool
When the size is a property of the delivery rather than of the document, such as rendering the same report at A4 for European recipients and Letter for North American ones. In that case the size belongs in the call, because it changes per recipient and the markup does not.
Frequently asked
Is css page size 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.
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.
Set PDF margins in an API request
One value for all four sides, or an object naming each side, defaulting to 1cm all round.
Generate a landscape PDF from an API
A boolean that turns the page rather than swapping its dimensions.
Scale PDF output from an API request
A multiplier applied to the whole rendered page, clamped between 0.1 and 2.
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.
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 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.
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.