Puppeteer PDF Paper Sizes: A Guide to Supported Formats

Puppeteer’s page.pdf() supports 11 named paper formats: Letter, Legal, Tabloid, Ledger, and ISO A0 through A6. Use format for a standard size, or set width and height with units for a custom sheet. The format option takes precedence over width and height; landscape controls orientation, and preferCSSPageSize lets a CSS @page rule control the sheet dimensions. [Puppeteer PaperFormat] [Puppeteer PDFOptions]

Supported Puppeteer PDF paper sizes

The Puppeteer PaperFormat reference lists these presets and dimensions. Inches are shown as width × height in the listed orientation; centimeters provide a convenient metric equivalent. [Puppeteer PaperFormat]

Preset	Inches (width × height)	Centimeters (width × height)
Letter	8.5 × 11	21.59 × 27.94
Legal	8.5 × 14	21.59 × 35.56
Tabloid	11 × 17	27.94 × 43.18
Ledger	17 × 11	43.18 × 27.94
A0	33.1102 × 46.811	84.1 × 118.9
A1	23.3858 × 33.1102	59.4 × 84.1
A2	16.5354 × 23.3858	42 × 59.4
A3	11.6929 × 16.5354	29.7 × 42
A4	8.2677 × 11.6929	21 × 29.7
A5	5.8268 × 8.2677	14.8 × 21
A6	4.1339 × 5.8268	10.5 × 14.8

Use the documented preset spelling, such as format: 'A4' or format: 'Letter'. The type accepts uppercase, lowercase, and capitalized variants, but conventional capitalization makes configuration easier to read. These are Puppeteer PDF page dimensions; they do not guarantee that a particular printer tray or print provider accepts a format.

Choose a preset, custom size, or CSS page size

Use a named format

Choose a preset when the output must follow a known paper standard. Letter and Legal are portrait formats; Tabloid is listed as 11 × 17 inches and Ledger as 17 × 11 inches. For other listed sizes, use the dimensions in the table. Set landscape: true when you want the selected sheet rotated. Orientation is an option, not a separate paper preset.

Set a custom size

When no preset matches the required sheet, specify both width and height. Each value accepts a number or a string with a unit. Unit-bearing strings state the intended measurement explicitly:

await page.pdf({
  path: 'custom.pdf',
  width: '210mm',
  height: '280mm',
  margin: {
    top: '10mm',
    right: '12mm',
    bottom: '10mm',
    left: '12mm',
  },
});

Do not set format alongside custom dimensions expecting the dimensions to win. When format is set, Puppeteer gives it precedence over width and height. Remove format to use a custom sheet. [Puppeteer PDFOptions]

Let print CSS set the physical page size

If your print stylesheet owns the page dimensions, define them with CSS @page and set preferCSSPageSize: true. With the default value, false, Puppeteer scales the page content to fit the paper size configured in its PDF options. Avoid competing size declarations: choose either a Puppeteer preset/custom dimensions or CSS page sizing as the controlling source. [Puppeteer PDFOptions]

await page.addStyleTag({
  content: '@page { size: A4; margin: 12mm; }',
});

await page.pdf({
  path: 'css-sized.pdf',
  preferCSSPageSize: true,
});

Runnable Node.js example

This example launches Chromium, loads a page, and writes an A4 PDF. Install Puppeteer with npm install puppeteer, save this as make-pdf.mjs, then run node make-pdf.mjs. Replace the URL with a page you are authorized to access.

import puppeteer from 'puppeteer';

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',
    format: 'A4',
    landscape: false,
    margin: {
      top: '12mm',
      right: '12mm',
      bottom: '12mm',
      left: '12mm',
    },
  });
} finally {
  await browser.close();
}

The example uses documented options; it is not a claim that the code was run. Puppeteer’s Page.pdf() generates output using the print CSS media type. To render screen styles instead, call await page.emulateMediaType('screen') before page.pdf(). [Puppeteer Page.pdf()]

Related PDF options and print behavior

Option	What it controls	Practical detail
format	Named paper preset	Defaults to Letter; takes precedence over width and height.
width, height	Custom sheet dimensions	Use numbers or unit-bearing strings; omit format when relying on these.
landscape	Page orientation	Defaults to false; set true to rotate the page.
preferCSSPageSize	Which source controls physical sheet size	Defaults to false; set true to honor CSS @page size.
margin	Printable content inset	Configure top, right, bottom, and left separately; the default is no margins.

Paper size and content layout are separate concerns. A correct A4 sheet can still have unexpected page breaks or clipped content if the print stylesheet is designed for another width. Check the rendered PDF’s page dimensions and content placement after changing the size.

PDF printing can also change colors: Puppeteer modifies colors for print by default. If exact CSS colors are needed, use the CSS -webkit-print-color-adjust property. This behavior is separate from paper size. [Puppeteer Page.pdf()]

Or skip the browser setup

For a screenshot or PDF of a web page, ScreenshotNeo provides a website screenshot API and MCP server. Its API can return a PDF, so you can make a single request instead of launching and managing a browser. See the ScreenshotNeo API documentation for PDF parameters and other options.

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

import requests

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

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  format: 'pdf',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('page.pdf', Buffer.from(await res.arrayBuffer())));

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses report the page verdict and billing status in headers. An MCP server gives AI agents tools for screenshots and PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

Troubleshooting

The PDF has the wrong dimensions

• Cause: format is set alongside width and height. Fix: remove format for custom sizing, or remove custom dimensions to use the preset.
• Cause: CSS declares an @page size, but Puppeteer options still control the sheet. Fix: enable preferCSSPageSize: true if CSS should determine physical size.
• Cause: the selected format is correct but orientation is unexpected. Fix: set landscape: true or false explicitly and verify the resulting dimensions.

Content is scaled or has unexpected margins

With preferCSSPageSize off, Puppeteer documents scaling content to fit the selected paper size. Set it to true when CSS @page should take priority. Also inspect the separate margin option and the print stylesheet, since page size alone does not determine content inset or page breaks.

Styles or colors differ from the browser view

page.pdf() uses print media by default. Use page.emulateMediaType('screen') before generating the PDF if screen CSS is intended. For print output that needs exact colors, use -webkit-print-color-adjust in CSS. [Puppeteer Page.pdf()]

A preset is not accepted by the installed package

The reference cited here is for Puppeteer 25.12.0. Check the API documentation matching your installed version when a preset or option differs; do not assume every installed release has the same browser mapping or API details. Puppeteer’s supported-browser reference maps version 25.12.0 to Chrome for Testing 154.0.8037.57 and Firefox 156.0.1. [Supported browsers]

Performance, reliability, and cost considerations

• Page size: large formats such as A0 produce larger physical pages, but paper size alone does not specify the document’s content or image resolution. Keep the print layout and expected output dimensions aligned.
• Reliability: use explicit dimensions and units for custom paper, and avoid setting competing size sources. Keep your Puppeteer package version and its matching browser installation aligned with the versioned documentation.
• Rendering: page loading and print CSS affect completion and appearance independently of the selected sheet. Choose a navigation readiness condition suited to the site, and review print-specific styles for page breaks and content fit.
• Cost: running Puppeteer yourself has no per-PDF ScreenshotNeo charge, but your environment bears browser runtime and infrastructure costs. For an API-managed screenshot/PDF workflow, ScreenshotNeo’s stated plans are free for 1,000 shots/month, then $5 for 3,000, $15 for 15,000, $39 for 60,000, $99 for 250,000, and $249 for 1,000,000; yearly billing gives two months free. All features are on every plan. See current details at ScreenshotNeo.

FAQ

What is Puppeteer’s default PDF paper size?

The documented format default is Letter.

Can I use millimeters for a custom size?

Yes. Set width and height to unit-bearing strings such as '210mm' and '280mm'.

Does CSS @page override format automatically?

No. Set preferCSSPageSize: true when CSS should control the physical sheet size.

Does changing paper size switch PDF output to screen CSS?

No. page.pdf() uses print media by default; use emulateMediaType('screen') to request screen styles.

Version and source notes

The paper-format and PDF options details here are based on Puppeteer 25.12.0 documentation. Consult the documentation for the version installed in your project if its supported formats or behavior differ. Sources: PaperFormat, PDFOptions, Page.pdf(), and supported browsers.