CSS @page Rule for PDF: Size, Margins, Named Pages & Headers
When generating PDFs from HTML, how do you control paper size, margins, and header/footer placement? The answer is the CSS @page rule.
@page is the core of the CSS Paged Media module, designed specifically for print and PDF output styling. This guide walks you through the full @page specification — from basic syntax to page pseudo-classes, named pages, and margin boxes — everything you need for professional PDF generation.
You can test every example in this article using the FUNBREW PDF Playground.
Basic @page Syntax
The @page rule defines styles that apply to the entire page box. The two most common properties are size and margin.
Setting Page Size
/* A4 portrait */
@page {
size: A4;
}
/* A4 landscape */
@page {
size: A4 landscape;
}
/* Explicit dimensions */
@page {
size: 210mm 297mm;
}
/* US Letter */
@page {
size: letter;
}
The size property accepts keywords like A3, A4, A5, B4, B5, letter, and legal. You can also specify width and height directly using mm, cm, or in units.
Setting Margins
@page {
size: A4;
margin: 20mm;
}
/* Different margins for each side */
@page {
size: A4;
margin: 25mm 20mm 30mm 20mm; /* top right bottom left */
}
Margins have a significant impact on PDF layout. For invoices, 20mm on all sides is typical. For reports, 25mm top/bottom with 20mm left/right works well.
Tip: The
@pagemargin is independent of the HTML body margin. The page margin defines the outer boundary, and the content area lives inside it where normal CSS applies.
Page Pseudo-Classes — :first, :left, :right, :blank
@page supports pseudo-classes that let you apply different styles based on page position.
:first — Different Layout for the First Page
Useful for cover pages, invoice headers, or any first-page customization.
/* Base settings for all pages */
@page {
size: A4;
margin: 25mm 20mm;
}
/* Larger margins on the cover page */
@page :first {
margin: 40mm 30mm;
}
:left / :right — Spread (Facing) Pages
For booklets and bound documents where left and right pages need different margins.
/* Left pages (even) */
@page :left {
margin-left: 30mm;
margin-right: 20mm;
}
/* Right pages (odd) */
@page :right {
margin-left: 20mm;
margin-right: 30mm;
}
The wider inner margin accommodates the gutter (binding edge).
:blank — Empty Pages
Applies to blank pages inserted by break-before: left or break-before: right.
@page :blank {
@top-center {
content: ""; /* Hide header on blank pages */
}
}
Named Pages — Multiple Layouts in One Document
The page property lets you assign different page configurations to different elements.
/* Cover page definition */
@page cover {
size: A4;
margin: 0;
}
/* Content page definition */
@page content {
size: A4;
margin: 25mm 20mm;
}
/* Landscape chart page */
@page landscape-chart {
size: A4 landscape;
margin: 15mm;
}
Assign named pages to elements using the page CSS property:
.cover-page {
page: cover;
}
.main-content {
page: content;
}
.chart-section {
page: landscape-chart;
}
<div class="cover-page">
<h1>Annual Report 2026</h1>
</div>
<div class="main-content">
<h2>Chapter 1: Overview</h2>
<p>...</p>
</div>
<div class="chart-section">
<img src="chart.png" alt="Revenue trends" />
</div>
Named pages let you produce a single PDF where the cover has no margins, body pages use A4 portrait, and chart pages use A4 landscape — all from one HTML source.
Margin Boxes — Headers, Footers, and Page Numbers
Margin boxes are defined inside @page rules and place content in the page margin area. This is the CSS-native mechanism for PDF headers, footers, and page numbers.
Margin Box Positions
@top-left @top-center @top-right
┌──────────────────────────────────────┐
│ │
@left-top @right-top
│ │
@left-middle @right-middle
│ Content Area │
@left-bottom @right-bottom
│ │
└──────────────────────────────────────┘
@bottom-left @bottom-center @bottom-right
There are 16 margin box positions in total.
Adding Page Numbers
@page {
size: A4;
margin: 25mm 20mm 30mm 20mm;
@bottom-center {
content: counter(page);
font-size: 10pt;
color: #666;
}
}
/* "3 / 12" format */
@page {
@bottom-right {
content: counter(page) " / " counter(pages);
font-size: 9pt;
}
}
counter(page) returns the current page number and counter(pages) returns the total page count.
Header and Footer Example
@page {
size: A4;
margin: 30mm 20mm 25mm 20mm;
@top-left {
content: "Acme Corporation";
font-size: 8pt;
color: #999;
}
@top-right {
content: "Confidential";
font-size: 8pt;
color: #c00;
font-weight: bold;
}
@bottom-left {
content: "Published April 2026";
font-size: 8pt;
color: #999;
}
@bottom-right {
content: counter(page) " / " counter(pages);
font-size: 8pt;
}
}
/* No headers or footers on the cover */
@page :first {
@top-left { content: ""; }
@top-right { content: ""; }
@bottom-left { content: ""; }
@bottom-right { content: ""; }
}
Practical Example — Invoice with Cover Page
Let's combine everything into a real-world invoice PDF with a cover page.
/* === Page Setup === */
@page {
size: A4;
margin: 20mm;
@bottom-center {
content: counter(page);
font-size: 9pt;
color: #888;
}
}
@page cover {
margin: 0;
@bottom-center { content: ""; }
}
@page :first {
@bottom-center { content: ""; }
}
/* === Layout === */
body {
font-family: "Inter", "Helvetica Neue", sans-serif;
font-size: 10pt;
line-height: 1.6;
color: #333;
margin: 0;
padding: 0;
}
.cover {
page: cover;
display: flex;
align-items: center;
justify-content: center;
height: 100vh;
background: linear-gradient(135deg, #1a365d, #2563eb);
color: #fff;
text-align: center;
}
.cover h1 {
font-size: 28pt;
margin-bottom: 10mm;
}
/* Invoice table */
.invoice-table {
width: 100%;
border-collapse: collapse;
break-inside: avoid;
}
.invoice-table th,
.invoice-table td {
border: 1px solid #ddd;
padding: 8px 12px;
}
.invoice-table th {
background: #f5f5f5;
text-align: left;
}
.total-row {
font-weight: bold;
font-size: 12pt;
break-before: avoid;
}
<div class="cover">
<div>
<h1>Invoice</h1>
<p>April 2026</p>
</div>
</div>
<section class="invoice-body">
<h2>Invoice Details</h2>
<table class="invoice-table">
<thead>
<tr>
<th>Item</th>
<th>Qty</th>
<th>Unit Price</th>
<th>Amount</th>
</tr>
</thead>
<tbody>
<tr><td>PDF Generation API (Pro Plan)</td><td>1</td><td>$50.00</td><td>$50.00</td></tr>
<tr><td>Additional Requests (100 units)</td><td>2</td><td>$10.00</td><td>$20.00</td></tr>
</tbody>
<tfoot>
<tr class="total-row"><td colspan="3">Total</td><td>$70.00</td></tr>
</tfoot>
</table>
</section>
You can send this HTML and CSS to the FUNBREW PDF API. Margin boxes require the quality engine with Chrome 131 or later. Verify the cover and page numbers in the actual output, including any fallback path.
Multi-Section Report Example
For documents that need different layouts for the cover, table of contents, body, and appendix:
@page cover {
size: A4;
margin: 0;
}
@page toc {
size: A4;
margin: 30mm 25mm;
@top-center {
content: "Table of Contents";
font-size: 9pt;
color: #666;
}
}
@page main {
size: A4;
margin: 25mm 20mm;
@top-left {
content: "Monthly Report";
font-size: 9pt;
color: #666;
}
@bottom-right {
content: counter(page);
font-size: 9pt;
}
}
@page appendix {
size: A4 landscape;
margin: 15mm;
@bottom-center {
content: "Appendix - " counter(page);
font-size: 8pt;
}
}
.cover { page: cover; }
.toc { page: toc; }
.main { page: main; }
.appendix { page: appendix; }
Engine Compatibility
@page support varies significantly between PDF generation engines.
| Feature | Chromium (Headless) | How to configure it in wkhtmltopdf |
|---|---|---|
size |
Yes | --page-size / --page-width / --page-height |
margin |
Yes | --margin-top/right/bottom/left |
:first / :left / :right |
Yes | Do not rely on CSS support |
| Named pages | Yes | Do not rely on CSS support |
| Margin boxes | Yes (Chrome 131+) | --header-html / --footer-html |
counter(page) / counter(pages) |
Yes (Chrome 131+) | --footer-right "[page] / [topage]", etc. |
Chromium-Based Engines
Puppeteer, Playwright, and FUNBREW PDF's quality engine use Chromium. They support size, margin, page pseudo-classes, and named pages; Chrome 131 added margin boxes and page counters. FUNBREW PDF falls back to fast when Gotenberg is not configured, so verify the actual output in your environment.
Important caveat: In Puppeteer's page.pdf(), set preferCSSPageSize: true when a CSS @page size declaration should take priority over format, width, or height. This is a Puppeteer option, not a FUNBREW PDF request parameter.
wkhtmltopdf
wkhtmltopdf uses the Qt WebKit engine. Rather than assuming consistent CSS support, use the documented --page-size, --margin-*, and --header-html / --footer-html options for page size, margins, headers, and footers.
wkhtmltopdf: Setting A4 Size with Zero Margins
The most reliable way to produce a full-bleed A4 PDF in wkhtmltopdf is to combine the --page-size flag with --margin-* flags set to 0, rather than relying on @page CSS:
wkhtmltopdf \
--page-size A4 \
--margin-top 0 \
--margin-right 0 \
--margin-bottom 0 \
--margin-left 0 \
input.html output.pdf
Reset the body's own margin as well when you want the content to reach the page edge. If WebKit's automatic scaling changes the intended dimensions, test --disable-smart-shrinking; this option controls scaling, not the page margins.
body {
margin: 0;
padding: 0;
}
For a deeper comparison of wkhtmltopdf and Chromium rendering differences, see "wkhtmltopdf vs Chromium Compared."
Common Mistakes and Fixes
1. Double Margins
/* WRONG: @page margin + body margin stack */
@page { margin: 20mm; }
body { margin: 20mm; }
/* CORRECT: Reset body margin */
@page { margin: 20mm; }
body { margin: 0; padding: 0; }
The @page margin defines the page boundary. Adding a body margin on top of that doubles the whitespace.
2. Page Size Not Applying
In Puppeteer, format, width, and height take priority over @page { size } by default.
// WRONG: format overrides @page
await page.pdf({ format: 'A4' });
// CORRECT: Let CSS @page control the size
await page.pdf({ preferCSSPageSize: true });
FUNBREW PDF's generation API has no preferCSSPageSize request parameter. Use page-size, orientation, margin-*, and CSS in your HTML, then verify the output from the selected engine.
3. Headers and Footers Not Showing
Margin box support is still limited in browsers. If they do not render, use this alternative approach:
/* Alternative: position: fixed for headers/footers */
.header {
position: fixed;
top: 0;
left: 0;
right: 0;
height: 15mm;
font-size: 8pt;
color: #999;
border-bottom: 0.5pt solid #ddd;
}
.footer {
position: fixed;
bottom: 0;
left: 0;
right: 0;
height: 10mm;
font-size: 8pt;
text-align: center;
color: #999;
}
@page {
margin-top: 25mm; /* Reserve space for header */
margin-bottom: 20mm; /* Reserve space for footer */
}
In paged media, position: fixed boxes can repeat on every page. Check multi-page output for overlap and engine-specific differences.
4. Named Pages Not Triggering Page Breaks
Assigning different named pages to sibling elements creates a page break at their boundary. If a nested structure does not switch pages as expected, align the targets at the same level and test again.
<!-- WRONG: Nested elements may not trigger breaks -->
<div class="wrapper">
<div class="cover-page">...</div>
<div class="main-content">...</div>
</div>
<!-- CORRECT: Top-level siblings -->
<div class="cover-page">...</div>
<div class="main-content">...</div>
Summary
The CSS @page rule is purpose-built for controlling the physical pages of printed and PDF output.
- Basics:
sizesets the paper dimensions,marginsets the page margins - Pseudo-classes:
:first,:left,:rightapply per-page styles - Named pages: Switch layouts within a single document
- Margin boxes: Place headers, footers, and page numbers with pure CSS
With a Chromium-based engine, the major @page features are well supported, letting you build sophisticated PDF layouts with CSS alone. Try your CSS live in the Playground.
For broader CSS techniques in PDF generation, see "HTML to PDF CSS Tips." For a full overview of PDF generation, check the "HTML to PDF Complete Guide." If something is not working as expected, the "PDF Troubleshooting Guide" has solutions for the most common issues.