CSS Print Styling for PDF Generation: Page Breaks, Headers & Layouts
Print CSS for Chromium-generated PDFs, tested with Screenshotly's fixed A4 settings: page breaks, repeating headers, page numbers, margins, and which @page rules are ignored.
Web pages are built for screens: fluid widths, sticky navigation, hover states. When Chromium prints one to PDF, it switches to your print CSS and splits the document into fixed-size pages. Most "broken PDF" reports are really print-layout issues you can fix in CSS.
This guide is about that CSS. It's written for Screenshotly's PDF output, which uses Chromium with fixed settings: A4 paper, 1 cm margins and background graphics on. Most of it applies to any Chromium-based PDF generator.
For the API request itself, see the PDF generation API guide. For invoice layouts, see Invoice and receipt PDFs.
How we tested
Each "tested" note below comes from rendering small test pages with the same page.pdf() settings Screenshotly uses (A4, 1 cm margins, printBackground: true) in a local Chrome 157 build, then inspecting the PDF's page size, text and fonts. Production uses a different Chromium build, and print behavior can change between versions, so check your own documents with a real capture.
The background references are the CSS Paged Media spec, MDN on @page and break-before, and Puppeteer's page.pdf() documentation.
Test results at a glance
| CSS | Result in our test |
|---|---|
@media print { … } |
Applied. The PDF uses print media |
@page { size: letter } or size: 100mm 150mm |
Ignored. Pages stay A4, and custom-size content is scaled onto A4 |
@page { size: landscape } |
Honored. Pages became A4 landscape (297 × 210 mm) |
@page { margin: 0 } or margin: 3cm |
Honored. Overrides the 1 cm default |
@page { @bottom-center { content: counter(page) } } |
Honored. Page numbers printed in the margin |
| Font inside a margin box | Not inherited from body. Set font-family on the margin box |
break-before: page |
Honored |
break-inside: avoid on a block |
Honored. The block moved to the next page whole |
<thead> in a long table |
Repeated at the top of every page |
position: fixed element |
Repeated on every page |
| Background colors | Printed (backgrounds are always on) |
@media (min-width: 900px) |
False, even with a 1920 px viewport. Breakpoints follow the paper width |
@font-face web font |
Loaded only when the request sends fullPage: true |
The rest of this guide explains how to use each of these.
Start with a print media query
Put print-only rules in a media query so your screen layout stays as it is:
@media print {
body {
font-size: 11pt;
line-height: 1.45;
color: #000;
background: #fff;
}
/* Remove everything that only makes sense on screen */
nav,
.sidebar,
.chat-widget,
.cookie-banner,
.no-print {
display: none !important;
}
}
Hide anything with position: fixed or position: sticky in print. Chromium repeats fixed elements on every page, so a fixed navigation bar ends up printed over the top of every page of your document.
Page breaks
Use the modern break-* properties. Chromium also accepts the older page-break-* names.
@media print {
/* Always start these on a new page */
.chapter,
.cover-page + * {
break-before: page;
}
/* Keep these in one piece */
.card,
.totals-block,
figure,
tr {
break-inside: avoid;
}
/* Don't leave a heading alone at the bottom of a page */
h1, h2, h3 {
break-after: avoid;
}
p {
orphans: 3;
widows: 3;
}
}
break-inside: avoid can't keep an element whole if it's taller than the printable area (277 mm on A4 with 1 cm margins). Split very long cards into sections that can break between them.
Repeating table headers
Put column headings in a real <thead>. Chromium repeats it at the top of each page a table spans, which is what you want for long invoices and statements.
<table class="line-items">
<thead>
<tr><th>Description</th><th>Qty</th><th>Amount</th></tr>
</thead>
<tbody>
<!-- rows -->
</tbody>
</table>
Repetition comes from the table header group. A styled first row inside <tbody>, or a header built from <div>s, is ordinary content and prints only once.
Margins, page size and orientation
Screenshotly's API applies 1 cm margins and has no margin field. In our test, an @page margin rule in your stylesheet took precedence:
@page {
margin: 18mm 15mm 20mm; /* top, left/right, bottom */
}
@page :first {
margin-top: 30mm; /* extra room for a letterhead on page one */
}
Paper size is a different matter. The renderer prints at A4 and doesn't ask Chromium to prefer CSS page sizes, so size: letter, size: legal and custom dimensions don't change the paper. Puppeteer's documentation describes this default as scaling the content to fit the paper size.
The landscape keyword was the exception in our test:
@page {
size: landscape; /* produced A4 landscape: 297 × 210 mm */
}
That's browser behavior, not an API option, so check it with your own document before you rely on it. If you need US Letter or Legal paper, Screenshotly can't produce it today.
Page numbers and running headers
The API doesn't add headers or footers. Instead, use CSS page margin boxes, which Chromium supported in our test:
@page {
margin: 20mm 15mm;
@top-left {
content: "Acme Inc. — Statement";
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
font-size: 9pt;
color: #555;
}
@bottom-center {
content: "Page " counter(page) " of " counter(pages);
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
font-size: 9pt;
color: #555;
}
}
Margin boxes don't inherit the font from body. In our sample invoice, the page numbers printed in a serif default font until we set font-family on the margin box itself.
Margin boxes are drawn inside the page margin, so give them room. With the 1 cm default there's space for a single small line. With margin: 0 there's none.
For content that must come from your data (an invoice number, a customer name), print it in the document body. Or use a fixed-position element: because Chromium repeats fixed elements on every page, a small position: fixed; bottom: 0 footer prints on each page. Reserve space for it with @page margin or body padding so it doesn't overlap your content.
Responsive layouts in print
Media queries in print are evaluated against the paper, not the browser viewport. The printable width of A4 with 1 cm margins is 190 mm, about 718 CSS pixels. In our test, a min-width: 900px query was false whether the viewport was 375 px or 1920 px wide, so the page printed its narrow layout.
Two things follow from this:
- If your desktop layout starts at 1024 px, the PDF will use your tablet or mobile layout. Add print rules for the layout you actually want.
- JavaScript still sees the viewport in
window.innerWidth. Charts that size themselves from the window can come out wider than the page. Give chart containers a fixed print width:
@media print {
.container { max-width: none; padding: 0; }
.chart { width: 180mm; height: 90mm; }
}
Colors and backgrounds
Screenshotly always prints background graphics, so colored table headers and badges appear in the PDF. Puppeteer's documentation notes that Chromium may still modify colors for printing unless you ask for exact colors:
@media print {
.brand-header,
.status-badge,
th {
-webkit-print-color-adjust: exact;
print-color-adjust: exact;
}
}
If the PDF may be printed in grayscale, check that status colors (paid, overdue) also have a text label.
Fonts
To keep viewport screenshots fast, the renderer skips web-font downloads unless the request sets fullPage: true. With fullPage omitted, our test page fell back to the next font in its stack. Either:
- send
fullPage: truewith every PDF request that uses@font-face, or - use a system font stack for print:
@media print {
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
}
}
Links
Links stay clickable in the PDF. Our test output kept the original href as a link annotation. If the document might be printed on paper, you can also print the address:
@media print {
.references a[href^="http"]::after {
content: " (" attr(href) ")";
font-size: 0.85em;
color: #444;
}
}
Limit this to a section such as references or payment links. Applied to every link, it clutters the page.
A complete starting stylesheet
@page {
margin: 18mm 15mm 20mm;
@bottom-center {
content: "Page " counter(page) " of " counter(pages);
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
font-size: 9pt;
color: #555;
}
}
@media print {
nav, .sidebar, .chat-widget, .cookie-banner, .no-print { display: none !important; }
.site-header { position: static; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
font-size: 11pt;
line-height: 1.45;
color: #000;
background: #fff;
}
.container { max-width: none; padding: 0; }
.chapter { break-before: page; }
tr, .card, figure, .totals-block { break-inside: avoid; }
h1, h2, h3 { break-after: avoid; }
p { orphans: 3; widows: 3; }
th, .status-badge { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
}
Serve it from the page you pass to the API. Screenshotly takes a URL, not an HTML string, so host your template on a route such as /documents/:id/print. Then request it:
{
"url": "https://app.example.com/documents/doc_123/print",
"format": "pdf",
"fullPage": true,
"waitForNetworkIdle": true
}
Checklist
- Everything fixed or sticky is hidden or made static in print.
- Tables use
<thead>, and rows and totals usebreak-inside: avoid. - Your layout is designed for a 718 px printable width, not for your desktop breakpoint.
- Page numbers have enough margin to print in.
- Requests send
fullPage: true, or the print CSS uses system fonts. - You've checked a capture of your longest real document.
PDF output is part of the Basic plan. Learn more on the URL to PDF API page, or read the PDF generation API guide, Invoice and receipt PDFs and Batch PDF generation and email delivery.
About the Author

Asad Ali
CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.
Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients
Frequently Asked Questions
How do I force a page break before a specific element?
Use break-before: page on the element. The older page-break-before: always also works in Chromium. Use it for chapter headings, cover pages and anything that should always start on a new page.
How do I stop a table row or card from splitting across pages?
Apply break-inside: avoid to the element. In our Chromium test, a 400 px block with this rule moved to the next page whole instead of splitting. A block can't be kept whole if it's taller than the printable area of a page.
Can I add page numbers without an API header/footer option?
Yes, with CSS page margin boxes: @page { @bottom-center { content: 'Page ' counter(page) ' of ' counter(pages); } }. In our test this printed 'Page 1 of 4' and so on. The margin box sits inside the page margin, so it needs a margin large enough for the text.
Can I make Screenshotly output Letter-size PDFs with @page size?
No. Screenshotly prints at A4 and doesn't ask Chromium to prefer the CSS page size, so size: letter and custom dimensions are ignored. In our test, the keyword landscape was still honored and produced A4 landscape pages.
Ready to capture your first screenshot?
Get started with 100 free screenshots. No credit card required.