How to Scale PDFs When Converting HTML to PDF

To scale PDFs when converting HTML to PDF, set paper size and margins first, then adjust the renderer’s content scale only if the content itself needs proportional enlargement or reduction. Also check print styles: Puppeteer uses print CSS by default, so a difference between screen and PDF output may come from @media print or @page, not the scale setting.

For Puppeteer, scale defaults to 1 and accepts values from 0.1 to 2. With preferCSSPageSize: false (the default), PDF options determine the paper size and content is scaled to fit. Set preferCSSPageSize: true when the CSS @page size should take priority. Playwright documents similar controls; check the API for your installed version.

1. Separate page geometry from content scale

These settings solve different problems:

Control	What it changes	Use it when
Paper size or `@page size`	The dimensions of each PDF page	The output page should be A4, Letter, or a specific custom size
Margins	The printable area inside each page	Content is too close to the edges, clipped, or unexpectedly cramped
Print CSS and media	Styles applied during PDF rendering	Layout, visibility, or typography differs from the browser view
Scale or zoom	The size of rendered content relative to the page	The geometry and print styles are correct, but all content needs proportional sizing

Changing scale to compensate for the wrong paper dimensions can hide the underlying issue and produce poor margins or unexpected page breaks. Set geometry first, then change one setting at a time.

2. Check print CSS and page rules

Puppeteer’s Page.pdf() generates a PDF with the print CSS media type. Rules inside @media print can change font sizes, widths, visibility, and layout; @page can specify page dimensions and margins. Review these rules before changing scale. Puppeteer documents the print-media behavior in its Page.pdf API reference.

@page {
  size: A4 portrait;
  margin: 12mm;
}

@media print {
  .screen-only {
    display: none;
  }

  body {
    font-size: 11pt;
  }
}

If you intend to print the screen-styled page with Puppeteer, emulate screen media before calling page.pdf(). Do this deliberately: screen layouts may not include print-specific page breaks or other print adjustments.

3. Generate a PDF with Puppeteer

The following Node.js example opens a page, waits for it to load, and saves an A4 PDF. It uses CSS page size as the source of truth and keeps scale at its default of 1. Install Puppeteer in your project with npm install puppeteer; the first run may also need to download a compatible browser.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });

    await page.pdf({
      path: 'output.pdf',
      preferCSSPageSize: true,
      printBackground: true,
      scale: 1,
    });
  } finally {
    await browser.close();
  }
})();

To use PDF options for the page dimensions instead, set preferCSSPageSize: false and specify format, such as 'A4', or use explicit width and height. Then set margins separately. If the whole layout should be smaller, try a scale below 1; if larger, try a value above 1, staying within the documented 0.1–2 range. Check your installed Puppeteer version because APIs and defaults can change.

4. Generate a PDF with Playwright

Playwright’s Page API also documents PDF options such as scale and preferCSSPageSize. This JavaScript example uses CSS page rules and the installed Playwright browser. Install with npm install playwright, then install the browser required by your environment using Playwright’s documented setup for your version.

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle' });

    await page.pdf({
      path: 'output.pdf',
      preferCSSPageSize: true,
      printBackground: true,
      scale: 1,
    });
  } finally {
    await browser.close();
  }
})();

Option names and availability can vary by language binding and release. Consult the Playwright Page API for the version in your project.

5. Use a repeatable sizing workflow

Record the renderer and version. Puppeteer, Playwright, wkhtmltopdf, and hosted services do not necessarily share option names or defaults.
Choose the intended paper dimensions and orientation. Decide whether CSS @page or the PDF call owns page size.
Set margins. Check the available content area before adjusting scale.
Inspect print styles. Search for @media print, @page, and print-specific visibility or sizing rules.
Render at scale 1. This gives you a baseline. Change just one variable at a time.
Inspect the PDF at its actual page size. Check clipping, line breaks, tables, page breaks, and text legibility.
Repeat using production inputs and versions. Browser version, fonts, page content, and deployment environment can affect the result.

6. Other renderer settings

wkhtmltopdf

wkhtmltopdf exposes page size or explicit dimensions, orientation, margins, and a load zoom factor as separate settings. Review the settings reference for the exact build you use. The reference is older than the current browser-library documentation, so verify its behavior with your deployed version before relying on it for production output: wkhtmltopdf usage and settings.

Hosted HTML-to-PDF services

A managed converter can reduce the work of operating browser or conversion infrastructure. DocRaptor documents conversion from HTML or a URL and a Prince-based engine; Browserless documents a PDF endpoint that accepts a URL or raw HTML; PDFShift publishes its current usage allowances and credit rules. Compare how each service renders your real HTML and CSS, its page-size controls, deployment effort, data handling, current limits, and costs. Documentation alone does not establish which service renders a particular document best.

7. Common problems and fixes

Symptom	Likely cause	What to check
The PDF looks smaller or larger than the browser page	Print CSS, page-size options, or fit-to-paper behavior differs from screen rendering	Check `@media print`, `@page`, paper options, and `preferCSSPageSize` before changing scale
Content is clipped at the edges	Margins are too small, page geometry is wrong, or content exceeds the printable area	Confirm dimensions and orientation; increase margins or adjust the layout
CSS page size seems ignored	The renderer gives PDF options priority	For Puppeteer or Playwright, check `preferCSSPageSize`; set it to `true` when CSS page dimensions should take priority
Pages break in unexpected places	Print styles or content dimensions differ from the assumptions in the layout	Inspect print CSS and the actual PDF at the intended page size; check long tables, images, and fixed-height elements
Changing scale does not fix the layout	The issue is more likely page geometry, margins, or print media	Restore scale to `1` and work through the sizing workflow in order
Output differs between development and production	Renderer version, browser, fonts, or input content differs	Record and align the deployed renderer and inputs; verify against the exact production combination

8. Performance, reliability, and cost

For a self-hosted browser renderer, you operate the browser process and its deployment environment. Include browser installation, font availability, memory and concurrency planning, and cleanup in your operational design. A hosted converter can remove some infrastructure work, but introduces a service dependency and plan or usage limits. The cited documentation does not establish a universal performance winner; measure with representative documents and your own concurrency, privacy, and reliability requirements.

For reliable output, use the same renderer release and browser version in development and production, ensure required fonts and assets are available, wait for the content your document needs, and inspect generated files for clipping and missing resources. For cost comparisons, calculate expected document volume against each provider’s current pricing and limits; hosted service terms can change.

9. Or skip the browser setup

If your task is to capture a webpage as an image or PDF rather than operate a PDF renderer, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call API returns an image or PDF. See the ScreenshotNeo API documentation for parameters and output options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

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 removes cookie banners, popups, and chat widgets before the capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.

10. FAQ

Should I use CSS `@page` or the PDF API to set paper size?

Either can define page geometry. Choose one source of truth and configure the renderer so it honors that choice. In Puppeteer and Playwright, preferCSSPageSize controls whether CSS page size takes priority.

Does scale change the paper size?

Scale changes the rendered content’s size relative to the page. Set page dimensions and margins separately.

What scale should I start with?

Start at 1 for Puppeteer, then adjust only after checking print CSS, dimensions, and margins. Confirm valid ranges and behavior in your renderer’s installed version.

Why does my PDF differ from a browser screenshot?

PDF rendering may use print media styles and page layout rules. Compare the print CSS with the screen styling, and choose the intended media behavior explicitly.