Pagination
Most of what goes wrong with a generated PDF goes wrong on page two. A table is cut through the middle of a row. Its header never appears again. The bank details that belong under the total end up alone on a page of their own.
Compose PDF breaks pages the way a typesetter would, and it does it without you writing any rules for the common cases: a table that is longer than its page simply continues, header and all.
The rules
Section titled “The rules”Tables break between rows, never through one. A row that does not fit moves whole to the next page, however tall it is.
Headers repeat. The header row is redrawn at the top of every continuation. Turn it off per table with Repeat header on new pages.
Footers choose their page. A totals row can sit on Every page or on the Last page only — a running subtotal versus a single grand total.
A block can refuse to split. Mark it Keep together and it moves whole rather than breaking across the page boundary.
A block can travel with the next one. Mark it Keep with next and it will not be left behind as the last thing on a page — the classic case is a heading that must not be orphaned from its table.
Things that follow other things stay behind them. Instead of fixing a box at a coordinate, set it to Follow another box with a gap. When the table above grows by nine rows, everything anchored below it moves down by nine rows, on whatever page that turns out to be.
Continuation pages can have their own design. Page one carries the letterhead; pages two and after carry a lighter version of it. Design that second page once and point the flowing content at it with Continues on.
Page numbers are resolved after the break points are known. Add one with
+ Page number in the page’s header or footer and it prints 3 / 7
correctly, because the total is only known once pagination has finished.
Side-by-side blocks move as a unit. Two columns whose contents line up — a totals box beside a notes box — break at the same place, so they stay level with each other on the next page instead of drifting apart.
Setting it up
Section titled “Setting it up”Page breaking is on by default: content that does not fit flows onto the continuation page. What an individual box does (Keep together, Keep with next, Follow) is set in the right-hand inspector; what a table does (Repeat header on new pages, footer placement, Min rows) is set in the table section of the same panel.
Nothing about pagination is configured at call time. It belongs to the template, so the same payload produces the same breaks whether it is rendered in the studio preview, exported from the browser, or returned by the API.
What the API tells you
Section titled “What the API tells you”The page count of a render is recorded server-side and reported as pages by
GET /v1/renders/{renderId}, so you can meter or log it without opening the
file. See the Render API.
Notes and limits
Section titled “Notes and limits”- A row taller than the page cannot be split, so it is moved to a page of its own rather than clipped.
- Continuation is bounded. A template that would flow forever — a row that never fits, for example — stops rather than generating pages without end.
- Page numbers belong to the page’s own header or footer, the part that repeats. A number typed into ordinary body content is not a page number and will not be resolved.
- Grouping is not the same as breaking. Rows that share a value can gather under a heading row (Group the rows), and those groups then break by the rules above; the payload stays a flat list either way.