htmlToPdf does not repeat table headers on a new page
-
What you'll see
A table in a PDF from
docly.htmlToPdfruns over a page break. The first page has the header row, and the second page continues with bare rows. The reader can no longer tell which column is which, and a short table that splits after its header leaves the header on its own at the bottom of the page.<table> <thead><tr><th>Check</th><th>Result</th></tr></thead> <!-- only on page 1 --> <tbody>…120 rows…</tbody> </table> -
What's actually happening
The header group is printed once, where the table starts. Chrome repeats
<thead>at the top of every page when you print from the browser, and it is easy to rely on that. htmlToPdf does not do it.Measured on 2026-11-21 with the plainest case possible: one unstyled
<table>with a<thead>and 120 body rows, no flex, grid, zoom oroverflowaround it. The table ran over two pages in both setups, and the header text appeared once, on page 1:Setup Page 1 Page 2 No options header, rows 1–63 rows 64–120, no header <!-- ChromePDF csspagesize -->,@page{size:A4;margin:0}header, rows 1–68 rows 69–120, no header Styling the table does not change this. A version styled as a card, with and without
overflow:hidden, behaved the same way. -
What to do
Short tables: keep them together
Most tables in a report are a few rows long. Wrap each one, together with its heading, in a block that may not break. When it does not fit, the whole block moves to the next page:
.card{break-inside:avoid;page-break-inside:avoid} <div class="card"> <h3>Performance</h3> <table>…</table> </div>Write both properties.
page-break-insideis the older name, and including it costs nothing. The price is white space: the rest of the page stays empty when a block moves. Accept it, or order the sections so that the large blocks start on a page of their own.Long tables: split them in code
A table that is longer than a page cannot be kept together. Split the rows into tables of a size that fits, and give each one the header:
function table(header, rows, perPage) { let out = ""; for (let i = 0; i < rows.length; i += perPage) out += '<table class="card"><thead>' + header + '</thead><tbody>' + rows.slice(i, i + perPage).join("") + '</tbody></table>'; return out; }Choose
perPagefrom a test PDF rather than guessing, because the print is scaled (see htmlToPdf shrinks the page to about 71 percent). Check the result withpdftotext -f 2 -l 2 out.pdf -: the first line of every page should be the header.
Last reviewed 21 Nov 2026