How to Fix PDF Page Breaks in HTML

Page breaks are the #1 developer complaint about HTML-to-PDF conversion. Tables get cut mid-row, headings appear at the bottom of pages with no content following them, and images get sliced in half.

Here's how to fix every common page break problem.

The CSS Properties You Need

/* Prevent elements from being split across pages */
tr, .card, .item, figure, blockquote {
  break-inside: avoid;
  page-break-inside: avoid; /* Legacy support */
}

/* Keep headings with the content that follows */
h1, h2, h3 {
  break-after: avoid;
  page-break-after: avoid;
}

/* Repeat table headers on every page */
thead {
  display: table-header-group;
}

/* Control orphans and widows */
p, li {
  orphans: 3;
  widows: 3;
}

/* Force a page break before an element */
.page-break {
  break-before: page;
  page-break-before: always;
}

The Problem with Most PDF Generators

Most HTML-to-PDF tools (wkhtmltopdf, Puppeteer, headless Chrome) rely entirely on the browser's CSS page break implementation. This works okay for simple documents but fails for:

• Tables: Rows get cut in half. Headers don't repeat.
• Cards/Grids: Flexbox and grid items split unpredictably.
• Images: Large images get cropped at page boundaries.

LightningPDF's Smart Page Breaks

LightningPDF solves this with a page_break_mode option:

{
  "html": "<table>...</table>",
  "options": {
    "page_break_mode": "auto"
  }
}

Modes

Mode	Behavior
auto	Smart page breaks: avoids splitting rows, repeats headers, respects CSS
css	Only respects your CSS break rules
none	No special page break handling

What "auto" mode does:

1. Adds break-inside: avoid to all table rows, cards, and block elements
2. Forces display: table-header-group on <thead> elements
3. Prevents breaks after headings
4. Sets orphan/widow minimums to 3 lines
5. Runs a JavaScript pre-render pass to detect elements that would be split

The Native Engine Advantage

For structured documents (invoices, receipts, reports), LightningPDF's native Go engine handles page breaks perfectly because it controls the layout directly:

• Tables automatically split between rows (never mid-row)
• Headers repeat on every page
• Content height is pre-calculated before rendering

This is why native engine PDFs generate in under 100ms — no browser rendering needed.

Quick Fix Checklist

1. Add break-inside: avoid to table rows and card elements
2. Add break-after: avoid to headings
3. Set display: table-header-group on <thead>
4. Set orphans: 3; widows: 3 on paragraphs
5. Use LightningPDF's page_break_mode: "auto" for automatic handling

Try It Free

Sign up for LightningPDF and get 50 free PDFs per month with smart page break handling built in.

Related Reading

• HTML to PDF: The Complete Guide — All approaches to HTML-to-PDF conversion
• Generate PDFs in Node.js — Step-by-step Node.js tutorial
• Generate PDFs in Python — Python integration guide
• Generate PDFs in Go — Go tutorial with invoice example
• Best PDF APIs in 2026 — Full API comparison