Docly Developers
Knowledge base Pitfall Workaround available

htmlToPdf does not repeat table headers on a new page

In shortWhen a table in docly.htmlToPdf is split across two pages, the rows on the second page have no header row: <thead> is not repeated, although Chrome repeats it in ordinary print. This holds for a plain table in default HTML, with and without <!-- ChromePDF csspagesize -->. Keep short tables together with break-inside:avoid on a wrapping block so they move to the next page whole. For a long table that has to span pages, split the rows in code into several tables that each carry their own header.
Applies to APIPDF
  1. What you'll see

    A table in a PDF from docly.htmlToPdf runs 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>
  2. 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 or overflow around it. The table ran over two pages in both setups, and the header text appeared once, on page 1:

    SetupPage 1Page 2
    No optionsheader, rows 1–63rows 64–120, no header
    <!-- ChromePDF csspagesize -->, @page{size:A4;margin:0}header, rows 1–68rows 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.

  3. 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-inside is 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 perPage from a test PDF rather than guessing, because the print is scaled (see htmlToPdf shrinks the page to about 71 percent). Check the result with pdftotext -f 2 -l 2 out.pdf -: the first line of every page should be the header.

Last reviewed 21 Nov 2026