It paginates wrong
Table headers do not repeat on the next page
A long table breaks across pages and only the first page has column headings. Every page after it is a wall of numbers with nothing to say what they are.
What is actually happening
Header repetition is driven by table sectioning, not by styling. The rows have to be inside a thead element for the layout to know they are headers, and a table built with div elements has no sections to repeat.
Confirming it is this and not something that looks like it
Look at the markup rather than the CSS. If there is no thead, there is nothing to repeat, and no CSS property will create one.
The fix
Use a real table element with thead, tbody and tfoot. This is one of the few places where the semantic markup is not merely better practice, it is the mechanism: the paged layout uses the sections to decide what to repeat.
<table class="line-items">
<thead>
<tr>
<th scope="col">Description</th>
<th scope="col">Qty</th>
<th scope="col">Unit</th>
<th scope="col">Total</th>
</tr>
</thead>
<tbody>
<!-- Rows here. thead above repeats on every page they run onto. -->
</tbody>
<tfoot>
<tr><th scope="row" colspan="3">Total</th><td>1,240.00</td></tr>
</tfoot>
</table>If that was not it
These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.
- display: block applied to thead or tr by a responsive stylesheet, which destroys the table structure
- A table split into several tables to force breaks, each of which then needs its own thead
- tfoot placed after tbody in the markup, which is valid but repeats differently from what people expect
- position: sticky on the header row, which is a scrolling concept with no paged equivalent
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Header repetition is driven by table sectioning, not by styling. Anything rendering HTML to a paged medium has to make the same decision, so the fix travels with you if you change how the render happens.
Will this show up as an error in my logs?
No, and that is what makes it expensive. A document that renders wrong is still a successful render as far as every log line is concerned. It is found by someone opening the file, which is usually the customer.
Related failures
Problems people arrive at from the same starting point, or mistake for this one.
position: fixed elements repeat on every page or vanish
Fixed positioning means fixed to the viewport, and a paged document has one viewport per page or none at all depending on the engine.
Page breaks land in the wrong place
Nothing told the layout where it is allowed to break, so it breaks wherever the content runs out of page.
There is an extra blank page at the end
Something extends a fraction of a millimetre past the end of the last page.
Content is cut off at the right edge of the page
The element is wider than the page's content box and has nothing telling it to wrap.
Page numbers are missing or all show 1
Page numbers come from the footer template's special classes, not from CSS counters in the document body.
CSS for paged documents, and what actually works
Which parts of the paged media specification a browser-based render implements.
Everything that goes wrong, by category
The full list, grouped by where in the pipeline it breaks.
Paste your markup and see the rendered document, without signing up.