ScreenshotNeo

BlogHow-to

How to Change the PDF Page Width in Puppeteer

Set custom PDF widths in Puppeteer with width, format, CSS @page, and practical fixes for ignored sizes, scaling, margins, and print styles.

By the ScreenshotNeo team30 September 20268 min read

How to Change the PDF Page Width in Puppeteer

To change a PDF’s page width in Puppeteer, pass a width value to page.pdf():

await page.pdf({
  path: 'output.pdf',
  width: '8.5in'
});

The width option accepts a string or number. A unit-bearing string such as '8.5in', '210mm', or '816px' makes the intended size explicit. If you need a standard paper size, use format such as 'A4' or 'Letter'. When format is present, it takes precedence over custom width and height values. The official PDFOptions reference documents these rules and defaults.

1. The basic custom-width solution

This complete Node.js example launches Chromium, loads a page, and writes a PDF with a custom width:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();

await page.goto('https://example.com', {
  waitUntil: 'networkidle0'
});

await page.pdf({
  path: 'custom-width.pdf',
  width: '8.5in',
  height: '11in',
  printBackground: true,
  margin: {
    top: '0.5in',
    right: '0.5in',
    bottom: '0.5in',
    left: '0.5in'
  }
});

await browser.close();

Install Puppeteer with npm install puppeteer. The browser page’s viewport is separate from the PDF paper. You can set a viewport for responsive layout, but the PDF dimensions still come from page.pdf() options.

Width-only versus width and height

Set only width when the output can have a variable height or when you are using CSS pagination. Set both dimensions when you need a fixed sheet, such as an invoice or label.

// Fixed physical sheet
await page.pdf({
  path: 'letter.pdf',
  width: '8.5in',
  height: '11in'
});

// Custom wide sheet
await page.pdf({
  path: 'wide-report.pdf',
  width: '12in',
  height: '8.5in',
  landscape: true
});

Use one unit consistently. Inches and millimetres are easiest to review with a print vendor; CSS pixels can be useful when matching a browser design. Puppeteer converts the supplied value into the PDF paper dimensions.

2. Standard paper sizes with format

For common paper, prefer a named format:

await page.pdf({
  path: 'a4.pdf',
  format: 'A4',
  printBackground: true
});

Puppeteer’s documented formats include Letter (8.5 × 11 inches), Legal (8.5 × 14 inches), A4 (210 × 297 mm), and Tabloid (11 × 17 inches). The default format is Letter. If you supply format: 'A4' alongside width or height, the format wins, so remove format when a custom dimension is required.

Use landscape: true to swap the orientation of the selected paper. The default is portrait:

await page.pdf({
  path: 'legal-landscape.pdf',
  format: 'Legal',
  landscape: true
});

3. Let CSS define the PDF page width

When the document owns its print layout, define a page size with CSS:

<style>
  @page {
    size: 8.5in auto;
    margin: 0.4in;
  }

  @media print {
    .screen-only { display: none; }
  }
</style>

Then give CSS priority with preferCSSPageSize: true:

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

The PDFOptions documentation states that this option lets CSS @page size take priority over API dimensions. Its default is false. With the default, Puppeteer fits the page content to the paper size selected through PDF options.

Choose this route when templates already contain print CSS, different sections need controlled page breaks, or a design system owns margins and paper dimensions. Choose PDFOptions when the calling service must enforce a size regardless of page CSS.

4. Viewport width is not PDF width

page.setViewport() changes the browser’s CSS viewport. It influences responsive breakpoints and the layout that gets printed, but it does not set the physical PDF paper width. The Viewport API measures viewport dimensions in CSS pixels.

The viewport controls responsive layout while PDF options control the paper dimensions.
The viewport controls responsive layout while PDF options control the paper dimensions.
await page.setViewport({
  width: 1440,
  height: 900,
  deviceScaleFactor: 1
});

await page.pdf({
  path: 'report.pdf',
  width: '8.5in',
  height: '11in'
});

Use both settings when needed: viewport controls how the page lays itself out; PDF options control the sheet. A desktop viewport can still be printed onto a narrow page, which may cause wrapping or scaling.

5. Print CSS and screen CSS

page.pdf() uses print media by default. If your screen layout is the desired output, emulate screen media before generating the PDF, as described in the Page.pdf() documentation:

await page.emulateMediaType('screen');
await page.pdf({
  path: 'screen-styles.pdf',
  width: '8.5in',
  height: '11in',
  printBackground: true
});

Keep print and screen intent explicit. Print styles may hide navigation, change colors, or alter widths. If a width appears to be ignored, inspect both the active media type and any @media print rules.

6. Options that change usable width or apparent scale

Option Effect Default
width Custom paper width Unset
height Custom paper height Unset
format Named paper preset; overrides width and height letter
landscape Uses landscape orientation false
margin Reduces the content area inside the paper No margins
scale Scales rendered content 1
preferCSSPageSize Lets CSS @page override API size false
printBackground Includes background graphics and colors false

The documented scale range is 0.1 through 2. A smaller scale can make a wide layout fit, but it also makes text and images smaller. Increasing paper width is usually clearer than shrinking an entire report.

Margins and content width

A page that is 8.5 inches wide with 0.5-inch left and right margins has about 7.5 inches of usable content width. CSS margins, padding, borders, and table widths consume additional space. Check the complete box model before concluding that Puppeteer produced the wrong paper size.

Backgrounds and color

Set printBackground: true when the PDF must include colored sections, backgrounds, or chart fills. This does not change page width, but it often explains why a PDF looks different from the browser.

7. Complete reusable helper

A helper can make the sizing decision explicit and prevent conflicting options:

import puppeteer from 'puppeteer';

export async function renderPdf({
  url,
  output,
  format,
  width,
  height,
  landscape = false,
  preferCSSPageSize = false,
  scale = 1
}) {
  if (format && (width || height)) {
    throw new Error('Choose format or custom width/height, not both');
  }

  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1440, height: 900 });
    await page.goto(url, { waitUntil: 'networkidle0' });
    await page.emulateMediaType('print');

    const options = {
      path: output,
      landscape,
      preferCSSPageSize,
      printBackground: true,
      scale
    };

    if (format) options.format = format;
    if (width) options.width = width;
    if (height) options.height = height;

    await page.pdf(options);
  } finally {
    await browser.close();
  }
}

await renderPdf({
  url: 'https://example.com',
  output: 'custom.pdf',
  width: '210mm',
  height: '120mm'
});

8. Troubleshooting ignored widths and unexpected output

  1. format overrides your width. Remove format when using custom dimensions. This is the most common reason a width appears ignored.
  2. CSS @page is winning. If preferCSSPageSize: true is enabled, inspect the stylesheet. Remove the option or change the CSS size when API dimensions should control the result.
  3. You changed only the viewport. Set width or format in page.pdf(). A viewport is measured in CSS pixels and is not paper size.
  4. The content is too narrow or too small. Check landscape, margins, and scale. Large margins reduce usable width; a low scale shrinks everything.
  5. The page uses the wrong layout. PDF generation uses print media by default. Call page.emulateMediaType('screen') if screen styles are intended.
  6. Fonts or images change after capture. Wait for the page’s real readiness condition instead of relying only on navigation. For example, wait for a report container and for fonts to finish loading:
await page.goto(url, { waitUntil: 'networkidle0' });
await page.waitForSelector('#report');
await page.evaluate(() => document.fonts.ready);
  1. Long tables split badly. Add print CSS such as break-inside: avoid to rows or cards where appropriate, and test with the actual paper width. Avoid forcing every element to stay together because a very large block can create unexpected blank space.
  2. Headers and footers consume space. If you enable PDF header or footer templates, reserve room with top or bottom margins. Otherwise content can overlap or appear compressed.

9. Reliability and performance guidance

Launch one browser process and reuse it for multiple pages or jobs when your service captures many documents. Close each page after use and always close the browser in a finally block. Set a navigation timeout and handle pages that never become idle because of analytics or streaming connections.

page.setDefaultNavigationTimeout(45000);
await page.goto(url, { waitUntil: 'domcontentloaded' });
await page.waitForSelector('#report', { timeout: 15000 });

networkidle0 is useful for static reports but can wait forever on applications with long polling. In those cases, combine domcontentloaded with a selector or explicit readiness signal. Cache compiled templates and avoid loading unnecessary third-party resources when generating large batches.

PDF cost is mostly browser CPU, memory, network transfer, and waiting time. Wide pages can increase layout and rasterization work, while very high-resolution images increase memory use. Keep the paper width intentional, constrain untrusted URLs, and record the selected format, width, height, scale, and media type with each job so mismatches can be diagnosed.

10. cURL, Python, and Node.js alternatives

If you need a local Puppeteer workflow, the JavaScript examples above are the direct solution. For a service API that returns a rendered file, these request patterns are useful.

cURL

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

Python

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)

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}`);

11. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its one-call endpoint returns PNG, JPEG, WebP, or PDF output. Cookie banners, newsletter popups, and chat widgets are removed before the shot; bot checks, blank pages, failed loads, timeouts, and cache hits are never billed. Responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.

A capture service can remove common overlays before rendering the final file.
A capture service can remove common overlays before rendering the final file.

For PDF work, the service supports paper size, margins, landscape mode, and page ranges, along with full-page capture, custom CSS and JavaScript, waiting rules, headers, cookies, user agents, blocking rules, caching, signed links, asynchronous jobs, bulk capture, and a usage API. See the ScreenshotNeo documentation for request options.

The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to try the API.

12. Short FAQ

Can I use millimetres for width?

Yes. Pass a unit-bearing string such as width: '210mm'. Explicit units make physical output easier to review.

Does height: 'auto' work?

For CSS-controlled pagination, use an @page rule such as size: 8.5in auto with preferCSSPageSize: true. For fixed documents, set an explicit height.

Why is my A4 PDF still Letter-sized?

Check for format: 'Letter' or another format supplied by a wrapper. A format takes priority over custom dimensions.

How do I print the screen version?

Call page.emulateMediaType('screen') before page.pdf(), and keep printBackground: true if screen backgrounds are required.

Should I change viewport or PDF width first?

Set PDF width for the paper. Set the viewport separately when responsive breakpoints must produce a particular layout.