It paginates wrong
Flexbox and grid layouts break across pages
A grid of cards paginates by cutting a row in half, or a flex row that should stay together splits with two items on one page and one on the next.
What is actually happening
Break rules apply to items, not to containers, and a flex or grid container that is taller than a page has to break somewhere. The container itself cannot avoid breaking; only the things inside it can.
Confirming it is this and not something that looks like it
Put break-inside: avoid on the container and see if anything changes. If it does not, the rule is being correctly ignored because the container cannot fit on one page, and the fix belongs on the children.
The fix
Put break-inside: avoid on the items rather than on the container, so each card or row stays whole while the container is free to break between them.
.card-grid {
display: grid;
grid-template-columns: repeat(2, 1fr);
gap: 8mm;
}
/* The container will break. The cards should not. */
.card-grid > * {
break-inside: avoid;
}
/* Rows of a flex layout: wrap so each line is a break opportunity. */
.detail-row {
display: flex;
flex-wrap: wrap;
gap: 4mm;
break-inside: avoid;
}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.
- gap on a container, which is not a break opportunity and can push a row over the boundary
- align-items: stretch making every item the height of the tallest, so one tall item forces an early break
- Nested grids, where the break rule has to be on the innermost item
- Multi-column layout, which paginates differently again
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Break rules apply to items, not to containers, and a flex or grid container that is taller than a page has to break somewhere. 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.
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.
Table headers do not repeat on the next page
Header repetition is driven by table sectioning, not by styling.
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.
The header and footer do not appear
Header and footer templates are rendered in their own context with none of the document's CSS, and with a default font size of zero in some engines.
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.