Puppeteer page.pdf() viewport and pagination limits when generating multi-page documents

Question

I'm using Puppeteer to generate PDFs from rendered HTML pages via page.pdf(), and I need to understand the documented limits of this API before committing to it for a reporting feature.

My understanding is that page.pdf() captures the page as Chrome's print pipeline sees it, with options like format, margin, printBackground, and scale. What is unclear to me is how much control I actually have over pagination. Content that flows beyond a single page seems to break according to Chrome's print layout rather than anything I configure directly, and CSS like page-break-before appears to be the only lever.

I'm also unsure how viewport size and headless rendering interact with the output: whether the viewport at goto() time affects which content is laid out for the PDF, and whether font rendering differences between headless Chrome and a visible browser can shift line breaks and therefore page breaks.

Specific questions:

Does page.pdf() always capture the full document height, or can content outside the current viewport be omitted?
Is CSS print pagination (@page, break properties) the only supported way to control page breaks?
Should the viewport be fixed explicitly before calling page.pdf() to get deterministic output?

Tasadduq Burney · Answer

Answer to the three core questions

Content omission? page.pdf() always renders the entire DOM that has finished loading. Elements outside the current viewport are not clipped; they appear in the PDF as long as they are part of the rendered tree and are not hidden by CSS overflow or display:none. If content is loaded lazily or injected after the PDF call, it will be missing unless you wait for it.
  Control over page breaks? The only way to influence where a page ends is through CSS that is evaluated by Chrome’s print pipeline. Supported directives are:
    
      @page (margin, size, @bottom-center, etc.)
      break-before / break-after / break-inside
      Deprecated page-break-before / page-break-after / page-break-inside
    
    Puppeteer itself provides no API to insert page breaks programmatically.
  Viewport setting for determinism? Yes. The viewport you set with page.setViewport before navigating determines the layout of the page when CSS uses viewport units (vw/vh), media queries, or responsive breakpoints. The print engine ignores the viewport for page size, but the rendered DOM that it prints depends on that layout. Setting a stable viewport that matches the intended print size (e.g., 8.5×11 in at 96 dpi ≈ 816×1128 px) ensures repeatable PDFs.

Practical steps for deterministic PDFs

Prepare the page
    
      Ensure all content is loaded: use page.waitForNetworkIdle() or explicit waits.
      Make fonts available in the headless environment (install them or host locally).

Set a fixed viewport
    await page.setViewport({ width: 816, height: 1128, deviceScaleFactor: 1 });

Apply CSS breaks
    /* Example: force a new page before each section */
section::before {
  content: "";
  page-break-before: always;
}

Generate the PDF
    await page.pdf({ path: 'report.pdf', format: 'A4', printBackground: true });

Verify consistency
    
      Open the PDF in a viewer and count pages.
      Compare to Chrome’s Print preview in a headed browser with the same viewport.
      If counts differ, check for font differences or viewport‑dependent CSS.

When to ask for more diagnostics
If you observe page breaks that do not match your CSS, confirm whether the page uses viewport‑relative units or media queries that could be affected by the viewport you set. Also check for asynchronous content that might not yet be present when page.pdf() runs.

Puppeteer page.pdf() viewport and pagination limits when generating multi-page documents

1 answer

Answer to the three core questions

Practical steps for deterministic PDFs

When to ask for more diagnostics

Your perspective belongs here.

0 question comments