To keep a component together in a Headless Chrome PDF, add break-inside: avoid to that component in print CSS. To start a section on a fresh page, use break-before: page. Set the intended paper size and margins with @page, then regenerate and inspect the PDF: these rules guide pagination, but cannot guarantee that content taller than the usable page will fit intact.
Which CSS page-break rule should you use?
Chrome lays printed content out across pages using CSS fragmentation. A break rule can discourage a split within a component or force a new page before a section. Choose based on the result you want:
As an Amazon Associate I earn from qualifying purchases.
| Rule | Effect | Typical scope |
|---|---|---|
break-inside: avoid |
Requests that the element not be split internally across pages. | A card, figure, table row group, or other component that should remain together. |
break-before: page |
Forces a page break immediately before the element. | A chapter, report section, or other content that should begin on a new page. |
@page |
Sets the printed page size and margins. | The document’s overall page setup. |
These rules do different jobs: use an avoidance rule to influence a break inside a component, and a forced break when the next section must start on a new page. Chromium’s documentation describes fragmentation and these break controls, but behavior can vary with browser version and the geometry of the content.
Recommended Free Tools
How do you add the rules to print CSS?
Start with a print-only stylesheet and change the selectors and page dimensions to match your document:
#1 Best Overall
- 1 ream (500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
@media print {
@page {
size: A4;
margin: 18mm;
}
.keep-together {
break-inside: avoid;
}
.new-page {
break-before: page;
}
}Apply keep-together to the element that should stay in one piece, and new-page to the element that should begin a page. The example’s A4 size and 18 mm margins are starting values, not universal settings; choose dimensions that match the document you need to produce.
break-inside: avoid is a request, not a way to shrink content. When an element is taller than the available page area, keeping it intact may be impossible and can result in overflow or the element moving to another page. If that happens, reconsider whether the whole element needs to stay together or adjust its print layout.
Rank #2
- HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America. Each ream is wrapped in a polyurethane coated paper wrapper to protect the cut sheets from moisture damage
- Sheet size – 8.5 x 11; Thickness – 20 pounds; Brightness – 92 bright white
- HP Copy&Print20 20 pounds printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design)
- All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment; 100% satisfaction guaranteed; ColorLok technology provides more vivid colors, bolder blacks and faster drying
- Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office; HP Copy&Print20 print and copy paper prevents yellowing over time to ensure a long-lasting appearance for added archival quality
How can you diagnose the first bad break?
- Confirm the rendering path. Identify the Chrome or Chromium version and whether the PDF comes from the print dialog, the Headless Chrome command line, or an automated script.
- Find the first incorrect split. Inspect print preview or a saved PDF and note the element that breaks and the page where it happens. Checking the full output matters because a change can improve one break while creating excess blank space or overflow elsewhere.
- Check print layout constraints. Look for fixed heights or overflow clipping inherited from screen styles. If they are affecting the printed element, adjust those rules inside
@media print. - Apply the narrowest useful break rule. Put
break-inside: avoidon the meaningful component that should remain together, orbreak-before: pageon the section that needs a fresh page. - Set page geometry and regenerate. Define the intended size and margins in
@page, generate the PDF again, and review the entire document for new blank space, clipping, or overflow.
This is a practical diagnostic sequence, not a guaranteed fix for every layout. Without the document’s HTML, styles, target browser build, and expected pagination, no one selector or stylesheet can be identified as the exact solution.
How do you generate and inspect the PDF in Headless Chrome?
Chrome documents the --headless --print-to-pdf command-line options for creating a PDF. For example:
Rank #3
- 3 ream case (1,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
chrome --headless --print-to-pdf=output.pdf https://example.comReplace the URL and output filename with your own. If you do not want Chrome’s generated date, URL, and page-number decorations, add --no-pdf-header-footer. That option suppresses browser-generated headers and footers; it does not set the CSS page margins. Use the print dialog’s header-and-footer setting when printing interactively.
The command-line --timeout option sets a maximum wait before capture when content is still loading. Choose a value based on how the page actually loads; waiting longer is not a substitute for confirming that content has finished rendering.
Rank #4
- 5 ream case (2,500 sheets) of 8.5 x 11 white copier and printer paper for home or office use
- Multipurpose letter size copy paper works with laser/inkjet printers, copiers and fax machines
- Smooth 20lb weight paper for consistent ink and toner distribution; dries quickly and resists paper jams
- Bright white paper (92 GE; 104 Euro) offers great contrast for crisp printing and vivid color
- Virgin copy paper providing professional quality results; acid-free to prevent yellowing
For a repeatable application pipeline, Puppeteer provides a high-level API for browser automation, including PDF generation. It is an alternative way to automate printing, not a prerequisite for fixing CSS pagination.
Why might the same CSS behave differently?
Pagination depends on available page space, the size of the boxes being laid out, and the browser’s implementation of fragmentation. Chromium’s RenderingNG documentation says LayoutNG block fragmentation initially shipped in Chrome 102 and describes support for break controls in its documented fragmentation context. That is implementation documentation, not a guarantee that every browser engine or older release will paginate identically.
Best Value
- Made in USA: HP Papers is sourced from renewable forest resources and has achieved production with 0% deforestation in North America.
- Optimized for HP technology: All HP Papers provide premium performance on HP equipment, as well as on all other printer and copier equipment.
- Perfect everyday office paper: Superior quality, reliability, and dependability for high-volume printing at home, at school and in the office. Perfect for everyday black and white printing.
- Certified sustainable: HP Office20 20lb printer paper is Forest Stewardship Council (FSC) certified and contributes toward satisfying credit MR1 under LEED (Leadership in Energy and Environmental Design).
- ColorLok technology printing paper: ColorLok technology provides more vivid colors, bolder blacks and faster drying.
Chrome’s print page model uses a page box and content area. The size and margins set with @page therefore affect how much content can fit before a break. Keep the CSS page setup aligned with the paper dimensions you intend to produce.
If the problem is specifically that borders or other decoration look wrong where a box splits, rather than where the page break occurs, box-decoration-break: clone may be relevant: Chrome 130 introduced support for it in block fragmentation. It changes how box decoration is handled across fragments; it is not a general replacement for page-break rules.
What if printed headers or footers are the problem?
Do not confuse page margins with browser-generated decorations. CSS @page margins control the printed content area. Chrome’s --no-pdf-header-footer flag suppresses browser-generated decorations in command-line PDF output. Chrome 131 added support for generated content in page margin boxes, as described in its October 30, 2024 article on printed page margins; that is a separate CSS capability for content in the page margins.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
