Invoice PDF page breaks: a row split in half, and the total alone on the last page
An invoice template gets tested with five line items. It fits on one page and looks fine.
Then a customer orders thirty things, and the PDF comes back with a row cut in half across the page break, or with Subtotal and Tax at the bottom of page one and TOTAL sitting by itself at the top of page two.
It's an old problem. The Stack Overflow question about keeping a table row off a page break has about 240,000 views and was still getting edits in 2025, and the invoice-specific versions of it (this one, this one) have no answers at all. A Hacker News comment from October puts the mood well: headless Chrome, Puppeteer, wkhtmltopdf all tried, and "it really feels like it shouldn't be this hard".
It's less hard than it looks once you know which four rules matter. We measured each one rather than repeat the folklore.
The setup
Playwright 1.63 driving Chromium 153 headless, page.setContent() then page.pdf() on US Letter with half-inch margins. A plain HTML table, 14px sans-serif, each line item three lines tall, followed by a totals block (a <div> with Subtotal, Tax and TOTAL).
We read every page back with pdftotext and rendered the page boundaries to images. Puppeteer's page.pdf() drives the same print engine, so the results should carry over; we didn't run it separately.
Failure 1: a row cut in half
With no page-break CSS at all, 60 line items, Chromium cuts rows wherever the page ends. Item 27 gets its first two lines on page 2 and its "third line" on page 3:
Note the header, though. Description / Qty / Amount is repeated at the top of the next page without any CSS, because it's in a <thead>. Chromium repeats <thead> on every page of a table that spans pages. If your header is a plain first <tr> inside <tbody>, it won't be repeated. Move it into <thead>.
The fix for the row:
tr { break-inside: avoid; }
Same 60 items with that rule: none of the four page boundaries cut a row. Each one ends on a row's last line and the next page starts with the header and a complete row. The older spelling, page-break-inside: avoid, is an alias and does the same thing in Chromium.
Flex rows behave the same way. We rebuilt the table as display: flex divs: without a rule they split mid-row too, and with break-inside: avoid on the row div they stopped splitting. What you lose with divs is the repeated header, since only a real <thead> gets that.
Failure 2: TOTAL alone on the last page
Now a 13-item invoice whose totals block only just doesn't fit. Rows are whole (the rule above is on), but the block after the table splits like any other text:
This one reaches the customer looking like a mistake. The page they look at first has no total on it.
The obvious fix doesn't fully work:
.totals { break-inside: avoid; }
The block stays together now, but the whole thing moves to page 2. In our runs, page 2 was Subtotal, Tax and TOTAL with no line item above them. A total that doesn't sit under anything isn't much better.
What does work is telling Chromium the totals must not be separated from what comes before them:
.totals { break-inside: avoid; break-before: avoid; }
With that, Chromium carries the last line item over to page 2 along with the totals, and repeats the header above it:
Putting break-after: avoid on the last row (tbody tr:last-child { break-after: avoid; }) gave the same result in our runs. Use whichever reads better in your stylesheet.
Don't put the total in <tfoot>
It's tempting, since <tfoot> looks like it was made for totals. But Chromium repeats <tfoot> at the bottom of every page the table spans, just as it repeats <thead> at the top. A grand total in <tfoot> prints on page 1 as if it were the total for page 1.
Use <tfoot> for something that should repeat, like "continued on next page", and keep the real totals in a block after the table.
Where the rules stop
A row taller than a page still splits. We gave one line item a 70-line description. With tr { break-inside: avoid; } Chromium first pushed that row to a fresh page, leaving page 1 mostly empty, and then split it across pages 2 and 3 anyway, because it can't fit anywhere. The CSS can't help a row that's bigger than the page. If your descriptions can get that long, cap them in the table and print the full text in a notes section underneath.
wkhtmltopdf is a different engine. It's built on an old QtWebKit, not Chromium, and the unanswered question above is someone finding page-break-inside ignored on rows there. Nothing we measured here says anything about wkhtmltopdf. If you're still on it, that's one more reason to move.
Test with the longest invoice you have. Every one of these failures depends on where the page happens to end, so a template that passes with 5 rows and with 60 can still fail at 13. Generate a few lengths in a loop, open the boundaries, and look.
The short version
thead { display: table-header-group; } /* the default; only needed if something reset it */
tr { break-inside: avoid; }
.totals { break-inside: avoid; break-before: avoid; }
Header in <thead>, totals in a block after the table, never in <tfoot>.
Where we fit
None of this needs a service. It's CSS, and it works in the Chromium you may already be running. We make iReceipt PRO, an API that takes a template and JSON and returns the PDF, so you don't run a browser at all. The CSS above is still yours to write either way, and still worth testing against whatever renders your invoices: the page break lands wherever your content puts it.
Originally published at https://ireceipt.pro/blog/invoice-pdf-table-row-split-across-pages.
Comments
No comments yet. Start the discussion.