Pagination & fit
Automatic multi-page flow and fit-to-page.
Long documents break across pages automatically. This page explains the
break modes, running headers/footers, and the two anti-waste mechanisms:
fit (shrink-to-fit) and compact.
Page break modes
Control breaks with the pageBreaks field on
/v1/generate/html (templates apply their
own cached policy on top):
| Mode | Behaviour |
|---|---|
smart (default) | CSS rules + static analysis + in-browser DOM measurement. Keeps headings with their content, avoids orphan rows, protects <tr>, cards and figures from being cut. |
native | CSS rules only — the browser breaks where it wants. |
none | No break handling at all. |
{ "html": "...", "pageBreaks": "smart" }With the React SDK, <PageBreak /> forces a break and <NoBreak> keeps a
block on one page.
Running headers & footers
Two ways to repeat content on every page:
- Request fields — pass
headerand/orfooterHTML strings in the body of/v1/generate/htmlor/v1/generate/url. - In the markup — mark elements with
data-pf-header/data-pf-footer; the engine extracts them and turns them into page bands, reserving the top/bottom margin automatically:
<header data-pf-header>ACME SARL — Ouagadougou</header>
<main>...</main>
<footer data-pf-footer>Invoice 2026-001</footer>Fit-to-page (options.fit)
The classic bug: an invoice overflows by two lines and ships with an almost
empty page 2. With fit: "auto" (the default) a small overflow is
shrunk so the content fits one fewer page. Set "off" to disable:
{ "html": "...", "options": { "fit": "off" } }Compaction (options.compact)
compact: true opts a document into the wasteful-pagination compaction pass:
when the content could clearly fit in fewer pages, spacing is tightened and
the document reflows. Off by default — dense documents (statements, long
invoices) stay airy and fast.
The pagination score
When the pagination inspector runs, every generated PDF carries two headers:
X-Pagination-Score: 100
X-Pagination-Defects: 0X-Pagination-Score is a 0-100 quality score of the page layout;
X-Pagination-Defects counts issues found (cut rows, orphan headings...).
Log them to catch regressions in your templates.
Custom page sizes
options.width / options.height (e.g. "8cm" x "3cm" for a label)
override format entirely — pagination logic still applies.
Next steps
- HTML to PDF — the full request reference.
- Templates & variables — templates get an AI-derived break policy automatically.
- React & Next.js —
PageBreak,NoBreak,Header,Footeras components.