CSS PRINT LAYOUT · DEVELOPER GUIDE

# CSS for invoice PDFs: page size, margins and page breaks

A browser can render excellent invoices, but screen-first CSS often breaks when a document spans multiple printed pages. Start with the paper, define predictable breaks, and test with realistic data.

## 1. Choose the paper size deliberately

A4 and US Letter are not interchangeable. Select one format based on the document's intended audience and let your application pass that choice explicitly to the PDF renderer. CSS `@page` controls the printed page box; Puppeteer's `preferCSSPageSize` option gives a declared CSS page size priority over its format, width or height options.

```
@page {
  size: A4;
  margin: 18mm 14mm 20mm;
}

/* US Letter */
@page {
  size: Letter;
  margin: 0.7in 0.6in;
}
```

Do not declare multiple competing `@page` rules for the same document unless you intentionally use named pages. Keep the chosen format in one place so the API request and stylesheet do not disagree.

## 2. Keep table rows together

Long invoice tables can split in awkward places. Ask the browser to avoid breaking an individual row across pages, while still allowing the table as a whole to continue.

```
table {
  width: 100%;
  border-collapse: collapse;
}

thead {
  display: table-header-group;
}

tr {
  break-inside: avoid;
  page-break-inside: avoid; /* legacy fallback */
}
```

Keeping a row together is a request to the print layout engine, not a guarantee. Very tall rows may still need to split. Keep descriptions concise and avoid putting large images or nested tables inside a single row.

## 3. Control intentional page breaks

Use a dedicated class for sections that should start on a new sheet. Avoid hard-coded pixel offsets that only happen to work for one sample invoice.

```
.new-page {
  break-before: page;
  page-break-before: always; /* legacy fallback */
}

.keep-together {
  break-inside: avoid;
  page-break-inside: avoid;
}

@media print {
  .screen-only,
  .no-print {
    display: none !important;
  }
}
```

## 4. Reserve space for headers and footers

For a simple layout, put the company name, invoice number and customer details in the normal document flow. For repeating page headers or footers, use the PDF renderer's supported header/footer templates and reserve enough top or bottom margin. Test page one separately from later pages: the first page often has a larger title block.

## 5. Preserve background colors intentionally

Browser print defaults may alter colors. When a branded table header or status badge matters, combine the PDF option that prints background graphics with CSS print-color adjustment:

```
* {
  -webkit-print-color-adjust: exact;
  print-color-adjust: exact;
}
```

Do not rely on color alone to communicate invoice status or important totals. Maintain sufficient contrast in grayscale and on ordinary office printers.

## 6. Configure Puppeteer consistently

`Page.pdf()` uses the print CSS media type. Set the page size, orientation, margins and background option in one predictable request. Avoid waiting for remote images or fonts from arbitrary URLs in a document service; embed reviewed assets or serve them from a controlled location.

```
const pdf = await page.pdf({
  format: 'A4',
  landscape: false,
  printBackground: true,
  preferCSSPageSize: true,
  margin: {
    top: '18mm',
    right: '14mm',
    bottom: '20mm',
    left: '14mm'
  }
});
```

## 7. Test with ugly, realistic data

A one-line invoice is not a pagination test. Include a long customer address, a 40-row invoice, a very long product description, a discount, tax lines, a multi-page report and non-ASCII characters. Check both page count and visual output. Make sure the final total is not stranded by itself on a new page.

## Where Vervant fits

Vervant is building an HTML-to-PDF API for SaaS backends. Its prototype supports A4, Letter, Legal and Tabloid, explicit margins, background printing and landscape output. The hosted API is in private-beta preparation and is not publicly available yet. These guides are educational examples, not accounting or tax advice.

## References

- [Puppeteer Page.pdf() documentation](https://pptr.dev/api/puppeteer.page.pdf) — print media and PDF generation.
- [Puppeteer PDFOptions](https://pptr.dev/next/api/puppeteer.pdfoptions) — landscape, margins, print backgrounds and CSS page-size priority.
- [MDN: break-inside](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/break-inside) — controlling page and column breaks.

[Read the HTML-to-PDF security guide →](/guides/secure-html-to-pdf.html)
