DEV Community

Cover image for How to Fix PDF Page Breaks in HTML (The Complete Guide)
Digital Trubador
Digital Trubador

Posted on

How to Fix PDF Page Breaks in HTML (The Complete Guide)

#webdev #programming #tutorial #productivity

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.

PDF page breaks are the points where content splits across pages during HTML-to-PDF conversion, often causing tables, images, and text blocks to be cut awkwardly unless controlled with CSS properties or smart rendering engines.

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;
}
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Frequently Asked Questions

Why do my PDF tables get cut in the middle of rows?

Tables get cut mid-row because most HTML-to-PDF tools rely on the browser's basic page break algorithm, which does not understand table row boundaries. Fix this by adding CSS break-inside avoid to table rows, or use LightningPDF's automatic page-break-mode which prevents mid-row splits and repeats headers on every page.

What CSS properties control PDF page breaks?

The key CSS properties for PDF page breaks are break-inside avoid to prevent elements from splitting, break-before page to force a new page, break-after avoid to keep headings with their content, and orphans and widows set to 3 to prevent lonely lines. The legacy page-break prefix versions work in older tools.

How do I repeat table headers on every PDF page?

Add the CSS rule display table-header-group to your thead element. This tells the PDF renderer to repeat the table header row at the top of each page when a table spans multiple pages. LightningPDF's auto mode applies this rule automatically.

Does LightningPDF handle page breaks automatically?

Yes, LightningPDF offers a page-break-mode auto setting that automatically prevents mid-row table splits, repeats table headers, keeps headings with following content, and sets minimum orphan and widow lines. The native Go engine handles page breaks perfectly for structured documents like invoices and reports.

Related Reading

Top comments (0)