HTML and CSS for PDF: what works and how to check it
Published 3 min read
A page you built for a browser scrolls forever. A PDF does not: it has a fixed paper size, margins, page breaks, and a header and footer that repeat. That is why the same HTML can look right on screen and wrong on paper, and why it helps to know what a PDF renderer supports before you design for it.
This is what the rustedf.cloud renderer supports, with the pitfalls that come with it.
Layout that works
- The CSS box model, including
box-sizing, margins, andmin-andmax-sizes. - Tables with
colspanandrowspan, and header rows that repeat on every page the table spans. This is what keeps a long invoice or statement readable. - Flexbox, and a subset of grid (
grid-template-columnswith lengths,fr,autoandrepeat(), plusgap). position: relativeandabsolute,z-index, multi-column text, and lists.
Paged media
This is the part most web pages never use, and it is what a document needs.
@page { size: A4; margin: 20mm; @bottom-center { content: "Page " counter(page) " of " counter(pages); }}
.signature { break-inside: avoid; }h2 { break-after: avoid; }@pagesets the size, orientation and margins, and top and bottom margin boxes hold headers and footers, with the page number and the page count.break-before,break-afterandbreak-insidecontrol where a page may end. Usebreak-inside: avoidso a signature block or a total is never split across two pages.- Headings become the outline of the PDF, and
<a href>links stay clickable.
Painting
Colors, backgrounds, linear-gradient(), solid, dashed and dotted borders, border-radius,
box-shadow, opacity and overflow: hidden all work. 2D transforms such as rotate()
and scale() work too, but a transform only moves how an element is painted: the element
keeps the space it had. 3D transforms are ignored.
Images are PNG and JPEG, either uploaded to your account (asset:<id>) or embedded as
data: URLs. Simple SVG shapes (rect, circle, line) are drawn as vector shapes.
What to leave out
- JavaScript.
- Animations and transitions.
- Pseudo-classes such as
:hover, and anything else that only makes sense on a screen. @font-faceand@import. You do not need them: name a font family in your CSS and the service makes it available. See the Fonts guide.- Images that point to a web address. The service never fetches an address from a template.
None of these breaks the render by default. An unsupported feature is ignored and reported.
Check before it ships
Reading a list is not the same as knowing your document is clean. POST /v1/validate takes
the same body as a render and builds the document, but returns a report instead of a PDF,
and uses no credit.
{ "ok": false, "pages": 1, "diagnostics": [ { "kind": "UnsupportedProperty", "text": "filter", "context": "inside <p class=\"note\">", "count": 2 } ]}ok is true when there is nothing to report. Each finding names the kind of problem, the
property or tag involved, where it was, and how many times it happened. Among the kinds are
UnsupportedTag, UnsupportedProperty, UnsupportedSelector, ImageLoadFailed and
LayoutOverflow, which flags a box taller or wider than the page.
For tests, add "strict": true to a render. The same findings then fail the request with a
422, and no credit is used. A template that stays clean in your test suite stays clean in
production.
Read the full list in Supported HTML and CSS and Validating a document.
Keep reading
Getting started
HTML to PDF: library, headless browser or API? How to choose
Three ways to turn HTML into a PDF, what each asks you to run and maintain, what HTML and CSS you get, and a short list of questions that decide.
4 min read
Getting started
How to generate an invoice PDF with an API
Build an invoice template with a loop over items, currency and date formatting for each country, and render it to PDF with one request.
2 min read
Getting started
HTML to PDF API: generate a PDF with one request
Send HTML and data in one POST and get a PDF back. A curl example, a Node.js example, and what to know about images, limits and credits.
2 min read
Code and integrations
Generate a PDF in ASP.NET Core: MVC, Razor Pages and minimal APIs
Turn a Razor view into a PDF in ASP.NET Core with one API call: a view renderer, a print-ready view, an MVC action, a Razor Pages handler and the traps to avoid.
3 min read