Numbers, tables and totals / Line-item table
A line-item table that paginates without losing its header
The list of things being charged for, which has as many rows as the order had lines and therefore no idea in advance how many pages it will take.
Why this block is harder than it looks
A line-item table is the only block in most documents whose height is genuinely unknown when the stylesheet is written. Three lines and it sits comfortably above the totals. Ninety lines and it runs across four pages, and every boundary it crosses is a place where something can go wrong: a header that appears only on page one, a row split so the description is on one page and the amount on the next, a single orphaned row stranded at the top of the last page above the totals. None of those are visible while you are building the document with test data, because test data has four lines.
The decisions that make it work
Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.
- Use a real table element with thead, tbody and tfoot. The repeating-header behaviour that paginated layout gives you is attached to thead specifically, and a table built from divs with display: table-row gets none of it.
- Set break-inside: avoid on the row, not on the table. On the table it means the whole thing has to fit on one page, which for a ninety-line order means it fits on none and the renderer overrides you anyway.
- Give every column an explicit width and set table-layout: fixed. Automatic layout measures all the content at once, so a long description in row eighty silently changes the column widths of every row above it.
- Right-align the numeric columns and set font-variant-numeric: tabular-nums, so the digits form a column rather than a ragged edge.
- Let the description column wrap and forbid wrapping on the numeric ones. A quantity that wraps to two lines is always a bug and never a feature.
- Repeat the header on continuation pages, and consider marking it as a continuation. A header that reappears with no indication the table carried over reads, on paper, as the start of a second table.
The fragment
Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.
<table class="items">
<thead>
<tr>
<th class="desc">Description</th>
<th class="num">Qty</th>
<th class="num">Unit</th>
<th class="num">Amount</th>
</tr>
</thead>
<tbody>
<tr>
<td class="desc">Structural survey, ground floor</td>
<td class="num">1</td>
<td class="num">840.00</td>
<td class="num">840.00</td>
</tr>
<!-- as many rows as the order had -->
</tbody>
</table>
<style>
.items {
width: 100%;
border-collapse: collapse;
table-layout: fixed; /* measure once, not per page */
}
.items thead { display: table-header-group; } /* repeat on every page */
.items tr { break-inside: avoid; } /* a row is atomic */
.items th, .items td {
padding: 6pt 4pt;
border-bottom: 0.5pt solid #ccc;
vertical-align: top;
}
.items .desc { width: 58%; }
.items .num {
width: 14%;
text-align: right;
white-space: nowrap;
font-variant-numeric: tabular-nums;
}
</style>What breaks when it is built the obvious way
Building the table from divs. It looks identical on screen and it loses the two behaviours that exist only for real tables: the header does not repeat, and the renderer has no notion of a row to keep together. The bug then appears only on documents long enough to paginate, which is never the one you tested with.
How to prove it survived pagination
Render with enough rows to cross three page boundaries, not two. Two lets a header-repeat bug hide, because you look at page two and it is fine. Then read the last page: if a single row is sitting alone above the totals, set orphans and widows on the tbody and render again.
Where it sits in a finished document
This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The invoice template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.
Frequently asked
Will this fragment work on its own?
Not as a whole document. It has no page rule, no margins and no base type, because those belong to the document rather than to the block, and duplicating them in every fragment would mean thirty copies to keep in step. Paste it into a template that already has them.
Why does it look right in a browser and wrong in the PDF?
Because a browser window is one continuous surface and a document is a stack of fixed rectangles. Nothing in a scrolling view exercises a page boundary, so every break rule in the fragment is inert until the content is paginated. Render the real thing with enough content to cross two or three boundaries, then look.
Do I need a special option on the render request for this?
No. Everything on this page is CSS and markup, which is your side of the boundary. What the render has to give you is a real page size with real margins, and after that the layout is decided by the stylesheet.
Other parts of a document
The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.
A totals block that never splits across a page break
Subtotal, tax and grand total, sitting immediately below the thing most likely to overflow and therefore constantly at risk of being cut in half by a page break.
A tax breakdown table with one row per rate that stays together
A small table showing taxable amount and tax for each distinct rate in the document, which exists because a single tax line stops being enough as soon as an invoice mixes rates.
Showing a total in two currencies without the columns going ragged
A total repeated in a second currency, usually because the document is issued in one currency and has to be settled or reported in another.
An address block with no blank lines where a field was empty
Name, street, locality, postcode and country, set as a block, where any of the middle lines may be absent for a given record and none of the gaps should show.
Invoice, as a complete file
The whole document with this block already in place, ready to copy and change.
thead in paged output
The property carrying the weight here, with its real support status.
Every part of a document
The full list, grouped by the kind of problem the block poses.
Paste the fragment into the playground inside a page rule and see what it does at a real page size. That is the only way any of this gets confirmed.