Pagination

Pagination is part of the export pipeline. The library slices DOM-space primitives into page-space output while preserving manual breaks, page bands, and repeat regions.

Page break modes

pageBreak: "auto" | "manual" | "single"

Manual breaks

Use the React marker:

import { PageBreak } from "react-print-pdf";

<CoverPage />
<PageBreak />
<LineItems />

Or CSS page-break properties on real elements:

<section style={{ breakBefore: "page" }}>Appendix</section>
<section style={{ breakAfter: "page" }}>Summary</section>

Modern break-before / break-after and legacy page-break-before / page-break-after are both recognized. Accepted values: page, always, left, right. The walker emits a synthetic page break primitive at the element's top edge for break-before, and at its bottom edge for break-after. auto, avoid, and unset are no-ops.

Keep a block together

Use break-inside: avoid for cards, table-like rows, signatures, or approval blocks that should not split across pages.

<div className="[break-inside:avoid]">
  <h3>Approval</h3>
  <p>Keep this block intact.</p>
</div>

If the block is taller than the available page content height, the library warns and splits it rather than clipping content.

Headers and footers

await exportToPDF(printRef.current, {
  header: ({ pageNumber, totalPages }) => (
    <div className="flex justify-between text-xs text-gray-500">
      <span>Q4 Revenue Report</span>
      <span>{pageNumber} / {totalPages}</span>
    </div>
  ),
  footer: () => <div className="text-center text-[10px]">Confidential</div>,
});

Header and footer components are measured at the printable content width. Their primitives are placed in the top and bottom margin bands.

Repeating table headers

Add data-print-repeat to the element that should repeat on continuation pages.

<table>
  <thead data-print-repeat>
    <tr>
      <th>SKU</th>
      <th>Description</th>
      <th className="text-right">Amount</th>
    </tr>
  </thead>
  <tbody>{rows}</tbody>
</table>

You can import the attribute constant if you prefer not to hardcode the string:

import { PRINT_REPEAT_ATTR } from "react-print-pdf";

PRINT_REPEAT_ATTR === "data-print-repeat";

Current trade-offs

The paginator is intentionally conservative:

• break-inside: avoid can leave unused space near the page bottom
• widows and orphans are not implemented
• tall cards with a background-color and a uniform border continue cleanly across page breaks (rounded corners on start/end pages only, square edges in the middle). Mixed per-side border colors and gradient backgrounds disqualify the soft-split path — they fall back to a single atomic rectangle and may leave blank space on continuation pages. See RFC 0001 for the design.

Those are layout quality improvements, not blockers for the core pipeline.

Repeat-band scope

A repeat band only takes up space on continuation pages of its parent. A <thead data-print-repeat> inside a <table> reserves space at the top of every page that the table spans — not on pages before the table starts, and not on pages after the table ends. Content that follows the table sits flush against the last row, not below a phantom header gap.