Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsPC HealthRecommendedCrashes, freezes, slowdowns? Check your PC nowSpot repairable issues before they interrupt work.Check PC×
Skip to content
CSS

CSS Paged Media vs. Paged.js: When to Use a Polyfill

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use native CSS Paged Media first. If browser print preview produces the pages your project accepts, it is the simplest, standards-aligned solution. Add Paged.js when you need a paginated in-browser preview, running headers or footers, page counters, named page templates, scripted pagination hooks, or a repeatable headless-browser export. Paged.js is a JavaScript pagination engine and polyfill; it interprets print CSS, fragments content into pages, and creates a controllable preview or PDF workflow.

What each approach actually does

CSS Paged Media is the baseline

CSS Paged Media is the standards layer for splitting content into discrete printed pages. A stylesheet can define printable areas, paper size, orientation, margins and page-break behavior, usually with @media print, @page and the modern break-before, break-after and break-inside properties.

There is no pagination runtime to ship. The browser lays out the document and its print dialog or PDF command performs the export. That keeps the dependency surface small and gives users a useful fallback when JavaScript is disabled.

Native support is not complete. Browser engines differ in fragmentation, generated content and page sizing. The marks and bleed descriptors in the CSS Paged Media module currently have no browser support. Can I Use reports 95.45% global usage support for @page (August 2026), but that figure covers the feature’s usage support, not every paged-media descriptor or identical output in every browser.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Paged.js supplies the missing rendering layer

Paged.js is an open-source JavaScript library that paginates HTML in the browser to create PDF output. It acts as a polyfill for print-related CSS that browsers do not yet implement consistently. During a pagination pass it creates page boxes, applies generated content, and exposes hooks and handlers for custom behavior. The original source HTML remains available; the preview adds generated page elements and classes as an output layer.

Its documentation covers running headers and footers, page counters, named pages, generated content and fragmentation. It also provides a browser polyfill, an npm module and the pagedjs-cli command for headless-browser PDF generation.

Decision guide: which should you choose?

Requirement Native CSS Paged Media Paged.js
Conventional article, invoice or report Use it when print preview meets acceptance criteria. Usually unnecessary overhead.
Smallest dependency surface Best choice; no pagination runtime. Requires JavaScript, a validation pass and a pinned runtime for production.
Running headers, footers or page counters Support varies and is often insufficient. Designed for generated content and page furniture.
Named page templates Limited and engine-dependent. Supported by its polisher and pagination pass.
Paginated preview inside your application Browser print preview is outside your page. Strong fit; pages are rendered in the document.
Automated PDF export Possible through a browser automation stack, but pagination remains browser-controlled. Documented CLI and headless-browser path.
Maximum cross-browser portability Portable semantics, but output follows each browser’s implementation. More consistent only when browser and operating system are fixed; it still relies on browser layout primitives.

Choose native CSS when

  • Your document is a normal report, article or invoice and the target browser’s print preview already passes visual and pagination checks.
  • You want graceful behavior in browsers with no JavaScript and the fewest moving parts.
  • You can accept browser-specific differences and do not need generated margin-box content or scripted pagination hooks.

Choose Paged.js when

  • Readers must see a page-by-page preview before exporting.
  • You need book-like running heads, footers, counters, named pages or other generated content.
  • A publishing or server workflow needs a repeatable command-line PDF step.
  • You are prepared to pin a browser and operating system and inspect resulting PDFs.

Use a hybrid when both audiences matter

Write semantic print CSS first. Let that stylesheet provide a usable native fallback, then load Paged.js only for the authoring and export path. If JavaScript fails or a simple browser print is adequate, the document still has a sensible result. Treat the Paged.js page DOM as an output representation rather than changing your source document model.

Build a reliable native CSS version

Start with print media and page geometry

@media print {
  nav, .screen-only, .chat-widget { display: none !important; }
  a { color: #000; text-decoration: none; }
}

@page {
  size: A4 portrait;
  margin: 18mm 16mm 20mm;
}

@page :first {
  margin-top: 24mm;
}

h1, h2, h3 { break-after: avoid; }
figure, table, pre, blockquote { break-inside: avoid; }
.chapter { break-before: page; }

Keep print rules semantic: hide navigation, preserve readable contrast, avoid forcing every element onto a new page, and use break-inside: avoid selectively. Large tables and code blocks can still exceed a page; no CSS declaration can make oversized content fit without changing its size or allowing it to split.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Validate in the actual target browser

  1. Open the document in the browser and choose Print.
  2. Set the intended paper size and orientation. Disable browser-added headers and footers if your design supplies its own.
  3. Enable background graphics when color or shaded components are part of the acceptance criteria.
  4. Export a PDF and inspect page breaks, links, tables, images, widows and orphans, and the final page count.
  5. Repeat on every browser and operating system you promise to support; record the browser version with the PDF in your test artifacts.

Add Paged.js for publication-style pagination

Browser preview

Serve the HTML from a web server; the browser polyfill needs to fetch the document’s CSS. A minimal page loads your print stylesheet and the Paged.js script, then lets the library paginate the content:

Rank #2
Sale
HTML and CSS: Design and Build Websites
  • HTML CSS Design and Build Web Sites
  • Comes with secure packaging
  • It can be a gift option
<link rel="stylesheet" href="print.css">
<script src="paged.polyfill.js"></script>

Keep the source markup semantic and place page-specific rules in @page and generated-content declarations. Paged.js’s polisher converts those declarations into browser-readable DOM and CSS. Use its documented hooks or handlers when a project needs custom behavior, such as adding a class to a page containing a particular section.

Command-line PDF export

Install the CLI and library in a project, then run the documented command:

npm install --save pagedjs-cli pagedjs
npx pagedjs-cli index.html -o result.pdf

The CLI runs a headless browser. Its options cover page size, margins, landscape mode and hyphenation. Keep the command, dependency versions, browser version and operating-system image under source control or in a locked build environment.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Generated headers, footers and counters

Publication layouts commonly need a title in the running head and a page number in the footer. Paged.js supports the generated-content model and page counters described in its documentation. Design those elements as part of the page template, then verify that long headings, blank pages and section starts do not produce an unexpected header.

Do not assume that a successful preview guarantees an identical PDF on another machine. Line-height, font availability, hyphenation and pagination can change between browsers and operating systems. A fixed renderer environment is part of the document specification.

Performance, reliability and cost considerations

Native CSS

Native printing has no extra pagination pass or client-side library download. It is usually the fastest path for a short document, but automation requires you to control a browser yourself. The browser’s print implementation remains the source of truth, so a browser update can alter line wrapping or page breaks.

Paged.js

Paged.js performs additional layout work to fragment content and build page elements. Large documents, high-resolution images and complex scripts increase that work. The benefit is a visible page model, generated page furniture and a documented CLI. The trade-off is another runtime to test and another place where failures can occur.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

For reproducibility, pin the browser and operating system, install fonts explicitly, wait for images and web fonts before pagination, and archive a sample PDF in regression tests. If a PDF changes, compare the page count and the first page where geometry diverges rather than treating the change as a CSS-only issue.

Troubleshooting common failures

The print preview ignores a break

Check that the rule is inside @media print (or otherwise active for print), that the element is not inside a layout context with special fragmentation behavior, and that an older browser is not expecting the legacy page-break-* properties. Test the same rule in the target browser instead of relying on a different engine.

Headers or counters are missing

Native browser margin boxes are inconsistently implemented. Use Paged.js for generated headers, footers and counters, and inspect the generated page DOM. Ensure the Paged.js stylesheet and script are loaded from a web server rather than opening the file directly.

Rank #4
Sale
Web Design with HTML, CSS, JavaScript and jQuery Set
  • Brand: Wiley
  • Set of 2 Volumes
  • A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers

Page size is wrong in the PDF

Set @page size and the CLI’s paper-size option together. Some engines, especially Firefox, may require a manual PDF-size change in the print dialog. Disable browser headers and footers and confirm the PDF viewer’s reported media box before changing margins in CSS.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Content is clipped or overlaps

Look for fixed heights, absolute positioning, transforms, oversized tables and images, or a font that is missing in the export environment. Replace fixed heights with intrinsic sizing where possible, constrain media, and allow a deliberately splittable block to flow across pages.

Different machines produce different page counts

Lock browser and operating system versions, install the same fonts, and make hyphenation settings explicit. Differences in line-height, font metrics and hyphenation are renderer differences, not evidence that one CSS rule is universally wrong.

The CLI cannot load styles or assets

Run a local HTTP server, use resolvable URLs, and check the headless browser’s network log for blocked resources. Wait for asynchronous content before the pagination pass; otherwise images or web fonts may arrive after page measurements have been made.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your goal is simply a clean screenshot or PDF of a URL rather than a custom paginated authoring workflow, ScreenshotNeo makes one GET request and returns PNG, JPEG, WebP or PDF. It accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo documentation for all parameters. The same request in Python is:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

And in Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Every feature is on every plan: 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000, with yearly billing giving two months free. Create a free ScreenshotNeo account.

Practical recommendation

Prototype with native CSS and make its output your fallback. If the acceptance checklist includes running furniture, counters, named pages, an embedded preview or automated PDFs, add Paged.js and pin the rendering environment. This separates document semantics from the output mechanism while keeping a browser-only, no-library path available.

Frequently Asked Questions

Is Paged.js a replacement for CSS Paged Media?

No. It consumes the same print-oriented CSS ideas and polyfills features that browsers implement incompletely; your semantic print stylesheet remains useful without it.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can Paged.js guarantee identical PDFs in every browser?

No. It still depends on browser layout primitives, page-size handling, fonts and hyphenation. Consistency requires a fixed browser and operating system.

Do I need Paged.js for a one-page PDF?

Usually not. If native print preview meets the required size, margins and breaks, adding a pagination runtime adds complexity without a corresponding benefit.

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Read next

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Outdated Drivers Are Slowing You DownFree scan - exact matches

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.