Puppeteer PDF Options: Page Size, Margins, and Backgrounds
Set Puppeteer PDF paper size, margins, and backgrounds with clear examples, option precedence, print CSS, and fixes for common rendering problems.
Set PDF paper size, margins, and backgrounds in the options passed to Puppeteer’s page.pdf(). Use format for a standard paper size such as 'A4' or 'Letter', margin for the four page edges, and printBackground: true when CSS background graphics should appear. By default, Puppeteer uses Letter, renders with print CSS, and omits background graphics.
This guide covers the Node.js Puppeteer API. The examples write a PDF to disk and can be run with a current Node.js installation and Puppeteer package. See the official PDFOptions reference and Page.pdf() reference for the full API.
1. Install Puppeteer and create a PDF
In an empty project directory, install Puppeteer:
npm install puppeteerSave this as pdf.mjs. It navigates to a page, applies PDF options, and saves the result as output.pdf.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.pdf({
path: 'output.pdf',
format: 'A4',
printBackground: true,
margin: {
top: '15mm',
right: '12mm',
bottom: '15mm',
left: '12mm',
},
});
} finally {
await browser.close();
}Run it with node pdf.mjs. Replace the URL and option values for your document. The options that determine sheet size and printed appearance are explained below.
2. Choose the page size
Use a standard paper format
format selects a named paper format. Puppeteer documents Letter as the default. When you set format, it takes precedence over width and height, so do not set both expecting the dimensions to combine.
| Format | Dimensions |
|---|---|
| Letter | 8.5 × 11 in (21.59 × 27.94 cm) |
| Legal | 8.5 × 14 in (21.59 × 35.56 cm) |
| Tabloid | 11 × 17 in (27.94 × 43.18 cm) |
| Ledger | 17 × 11 in (43.18 × 27.94 cm) |
| A4 | 8.2677 × 11.6929 in (21 × 29.7 cm) |
| A3 | 11.6929 × 16.5354 in (29.7 × 42 cm) |
| A5 | 5.8268 × 8.2677 in (14.8 × 21 cm) |
Choose the format your users or downstream print workflow expects. Paper-format names and dimensions are documented in Puppeteer’s PaperFormat reference.
Set custom dimensions
For a nonstandard sheet, use width and height. Each accepts a string or number; explicit units make the intended size easier to review. Supported unit conventions are documented in PDFOptions.
await page.pdf({
path: 'custom.pdf',
width: '210mm',
height: '297mm',
});Here the custom dimensions express A4-sized paper, but using format: 'A4' is clearer when a named format is what you want. If format is present, it wins over these dimensions.
Let CSS choose the sheet size
When the page’s print stylesheet defines an @page size, set preferCSSPageSize: true to give that CSS size priority. Its default is false; in that mode CSS page dimensions are scaled to fit the paper selected through the PDF options.
await page.pdf({
path: 'css-sized.pdf',
preferCSSPageSize: true,
printBackground: true,
});For example, the page being captured can include:
@media print {
@page {
size: A4 landscape;
margin: 12mm;
}
}Pick one source of truth for paper dimensions: explicit PDF options or the page’s print CSS. If you need the CSS @page dimensions to govern the output, enable preferCSSPageSize. Use landscape: true for API-selected landscape orientation.
3. Set margins and orientation
The margin option has four independent, optional sides: top, right, bottom, and left. Each accepts a string or number. Puppeteer does not set a margin object by default; specify the values your document needs.
await page.pdf({
path: 'margins.pdf',
format: 'Letter',
landscape: true,
margin: {
top: '0.5in',
right: '0.65in',
bottom: '0.5in',
left: '0.65in',
},
});Use consistent units across all four sides, such as mm, cm, or in. If a page has no breathing room, check both the PDF margin and CSS page rules: a print stylesheet may also set @page margins. Avoid assuming that an unset API margin will override margins already present in the page’s CSS.
4. Include backgrounds and preserve print colors
printBackground is false by default. Set it to true to include CSS background graphics in the PDF. This affects backgrounds; it does not mean print media becomes screen media.
await page.pdf({
path: 'with-backgrounds.pdf',
format: 'A4',
printBackground: true,
});Print rendering can modify colors. To request exact CSS color adjustment, include this rule in the page’s stylesheet:
* {
-webkit-print-color-adjust: exact;
}omitBackground: true is a separate option: it hides the default white page background and permits PDF transparency. It is useful when transparency is intended, but should not be confused with enabling CSS backgrounds. If the desired result is a colored page or component background, set printBackground: true as well.
For a page that intentionally needs transparency:
await page.pdf({
path: 'transparent.pdf',
format: 'A4',
omitBackground: true,
printBackground: true,
});Whether transparent output is useful depends on the content and the PDF viewer or later processing step. Inspect the resulting file in the target workflow.
5. Choose print or screen media
page.pdf() renders with the print CSS media type. That means print-specific styles may change layout, hide elements, or choose different colors. To render using screen media instead, call page.emulateMediaType('screen') before generating the PDF.
await page.emulateMediaType('screen');
await page.pdf({
path: 'screen-styled.pdf',
format: 'A4',
printBackground: true,
});Prefer print media for documents designed for paper. Choose screen media when you specifically need the screen stylesheet in the PDF. The CSS media choice and the background option are independent: screen media does not automatically enable background printing.
6. Combine the options in a complete example
This example uses CSS for its sheet size, prints background graphics, applies exact color adjustment, and saves a PDF. The timeout and navigation behavior should be adapted for the page being rendered.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setContent(`
<!doctype html>
<html>
<head>
<style>
@page { size: A4; margin: 14mm; }
* { -webkit-print-color-adjust: exact; }
body { font: 16px sans-serif; background: #eef4ff; }
.panel { padding: 24px; background: #2457a7; color: white; }
</style>
</head>
<body><main class="panel">PDF content</main></body>
</html>
`);
await page.pdf({
path: 'styled.pdf',
preferCSSPageSize: true,
printBackground: true,
});
} finally {
await browser.close();
}For a URL instead of HTML, use page.goto() and wait for the content your page needs before calling page.pdf(). Avoid relying on a generic delay when the page provides a specific selector or other readiness signal.
7. Puppeteer PDF option quick reference
| Goal | Option or action | Behavior to remember |
|---|---|---|
| Choose named paper | format |
Defaults to Letter; takes precedence over width and height. |
| Choose custom sheet dimensions | width, height |
Used when format is not overriding them; strings or numbers are accepted. |
Use CSS @page size |
preferCSSPageSize: true |
CSS size takes priority; otherwise it is scaled to fit the API-selected paper. |
| Landscape output | landscape: true |
Default is false. |
| Print CSS backgrounds | printBackground: true |
Default is false. |
| Allow transparency | omitBackground: true |
Hides the default white background; separate from printing CSS backgrounds. |
| Set page edges | margin |
Optional top, right, bottom, left values; no API margin object is set by default. |
| Render screen styles | page.emulateMediaType('screen') |
Call before PDF generation; default PDF rendering uses print CSS. |
| Request exact print colors | -webkit-print-color-adjust: exact |
Use in page CSS when print color adjustment changes colors. |
8. Troubleshooting common PDF output problems
| Symptom | Likely cause | Fix |
|---|---|---|
| PDF uses the wrong paper dimensions | format overrides width and height, or CSS @page sizing is being scaled to fit. |
Remove the conflicting size settings. Set preferCSSPageSize: true when CSS should choose the sheet, or select the intended API format. |
| Background colors or images are missing | printBackground defaults to false. |
Set printBackground: true. Also check whether the print stylesheet removes or changes the background. |
| Colors look faded or differ from the page | Print rendering adjusts colors by default. | Add -webkit-print-color-adjust: exact to the page CSS and inspect the PDF in the intended viewer. |
| Content is clipped near an edge | Page content, CSS @page margins, or PDF margins do not fit together. |
Set explicit margins, inspect print-specific CSS, and confirm the selected paper format and orientation. |
| Layout differs from the browser viewport | page.pdf() uses print media by default. |
Review print styles, or call page.emulateMediaType('screen') before generating the PDF if screen styling is required. |
| Transparency appears white | The PDF may retain the default white background or the viewer/workflow may display transparency on white. | Use omitBackground: true when transparency is intended, and verify with a workflow that supports PDF transparency. |
| CSS page size seems ignored | preferCSSPageSize remains false, or a competing format is set. |
Enable preferCSSPageSize: true and remove contradictory size options. |
9. Reliability, performance, and cost considerations
PDF generation runs a browser render, so the page’s loading behavior affects how long the job takes and what content appears. Navigate with an appropriate readiness condition, wait for application-specific content where necessary, and close the browser in a finally block so failures do not leave a browser process running. If generating many PDFs, reuse browser instances sensibly rather than launching one per document, while isolating pages that need separate state.
Large pages, long full-page documents, complex CSS, and external assets can increase render time and memory use. No benchmark is implied here; measure with your page and deployment environment. For repeatable output, control the page data, media mode, paper settings, fonts, and assets. When the PDF is part of a user-facing workflow, log the input URL and selected PDF options so a rendering issue can be reproduced.
Running Puppeteer means operating the browser runtime and the compute used for rendering. Cost therefore depends on your infrastructure and workload. Consider queueing bursts and applying limits to page size and concurrency if resource use is variable. For a managed screenshot or PDF request, ScreenshotNeo offers a website screenshot API and MCP server; its documented options include PDF paper size, margins, landscape, and page ranges. See the ScreenshotNeo API documentation.
Or skip the browser setup
Request a PDF from a URL with one API call. ScreenshotNeo supports PDF output and PDF options including paper size, margins, landscape, and page ranges. This cURL example uses the API’s documented endpoint and your API key; see the docs for request parameters.
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.pdfCookie banners, newsletter popups, and chat widgets are removed before the shot, and each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status. An MCP server lets AI agents use the take_screenshot, get_page_info, and capture_pdf tools. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
10. FAQ
What is the default Puppeteer PDF paper size?
The documented default format is Letter.
Does Puppeteer print CSS backgrounds by default?
No. Set printBackground: true to include background graphics.
Can I use CSS @page to set the PDF size?
Yes. Set preferCSSPageSize: true so CSS page dimensions take priority.
How do I make the PDF use screen styles?
Call await page.emulateMediaType('screen') before page.pdf().
Does omitBackground turn on background printing?
No. It hides the default white background and permits transparency. Use printBackground: true to print CSS background graphics.
Are all options supported in WebDriver BiDi?
Puppeteer’s BiDi support documentation lists a subset of PDF options: format, height, landscape, margin, pageRanges, printBackground, scale, and width. If using BiDi, check the BiDi support documentation for the current supported set.
