To scale an HTML-to-PDF output correctly, set the paper size and margins first, then adjust the renderer’s content scale only if the whole layout needs proportional resizing. Also check print-specific CSS: Puppeteer generates PDFs using print media by default, so a change in appearance may come from @media print rules rather than a scale setting.
Separate page geometry from content scale
PDF layout has two related but distinct controls:
- Page geometry: paper dimensions, orientation, and margins. These determine the page and the space available for content.
- Content scale: a renderer’s scale or zoom setting. This enlarges or reduces the rendered content proportionally; it does not replace choosing the right page dimensions.
Start with the intended paper size and printable area. Then adjust scale only if the content as a whole is still too large or too small. If a document is clipped, cramped, or unexpectedly reflowed, inspect the page size, margins, and print styles before reducing scale.
Diagnose the output before changing settings
- Identify the renderer and installed version. Option names and defaults differ across browser libraries and older converters; check the API documentation for the version your application uses.
- Check which media styles are active. Puppeteer’s
Page.pdf()uses print CSS by default. Review@media printand@pagerules before treating a difference as a scaling issue. Puppeteer documents screen-media emulation when screen styling is intended instead: Page.pdf method. - Confirm paper dimensions and orientation. Compare the PDF options for format, width, height, and landscape with the CSS
@pagesize. Check whether the renderer lets CSS page dimensions take priority. - Review margins. Margins reduce the area available for content. An overly narrow printable area can make a design appear cramped even when its scale is correct.
- Change one setting at a time. Begin with scale
1in Puppeteer, then make a small adjustment only after geometry and styling are correct. This is a diagnostic approach, not a claim that a particular scale has been tested for every document. - Inspect the generated PDF at its intended paper size. Check page dimensions, clipping, line breaks, tables, and legibility using the same renderer version and input as production.
Scale HTML to PDF in Puppeteer
Puppeteer’s PDFOptions.scale defaults to 1 and its documented range is 0.1 to 2. Its preferCSSPageSize option defaults to false; with that setting, content is scaled to fit the paper size specified by PDF options. Set it to true when the CSS @page dimensions should take priority over width, height, or format. Defaults and ranges can change, so verify them against your installed release. See the Puppeteer PDFOptions documentation.
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com/report', { waitUntil: 'networkidle0' });
await page.pdf({
path: 'report.pdf',
format: 'A4',
printBackground: true,
margin: {
top: '15mm',
right: '15mm',
bottom: '15mm',
left: '15mm'
},
scale: 1,
preferCSSPageSize: false
});
await browser.close();In this example, the PDF options choose A4 and 15 mm margins; scale remains at its default. If your stylesheet declares the authoritative page dimensions, use preferCSSPageSize: true and define them in CSS, for example:
Recommended Free Tools
#1 Best Overall
- Convert your PDF files into Word, Excel & Co. the easy way
- Convert scanned documents thanks to our new 2022 OCR technology
- Adjustable conversion settings
- No subscription! Lifetime license!
- Compatible with Windows 11, 10, 8.1, 7 - Internet connection required
@page {
size: A4 portrait;
margin: 15mm;
}Do not specify conflicting page dimensions in CSS and PDF options without deciding which should win. With preferCSSPageSize: false, Puppeteer fits content to the paper size set in the PDF options; with true, CSS page size takes priority. The official API describes the PDF output as using the print CSS media type.
Configure scale in Playwright
Playwright’s Page API also documents scale and preferCSSPageSize. The latter defaults to false, meaning the CSS page size does not take priority over the PDF paper options. Check the API documentation for the language binding and release installed in your project before relying on an option or default: Playwright Page PDF documentation.
Rank #2
![Doxillion Free Document Converter – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/81tjL48MwxL.png._SL160_.png)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com/report', { waitUntil: 'networkidle' });
await page.pdf({
path: 'report.pdf',
format: 'A4',
printBackground: true,
margin: { top: '15mm', right: '15mm', bottom: '15mm', left: '15mm' },
scale: 1,
preferCSSPageSize: false
});
await browser.close();
})();For CSS-controlled page geometry, define @page and set preferCSSPageSize: true. Make a separate adjustment to scale only if the content itself needs proportional resizing.
Use wkhtmltopdf’s separate page and zoom settings
The wkhtmltopdf settings reference separates page size (or explicit width and height), orientation, margins, and load zoom factor. Treat page geometry and zoom as separate decisions there as well. The reference is older than current browser-library documentation, so verify behavior against the particular wkhtmltopdf build in use before shipping a production fix: wkhtmltopdf settings reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
When a hosted converter is a better fit
A managed conversion API can avoid operating browser-rendering infrastructure yourself. DocRaptor documents HTML content or URL conversion with a Prince-based engine and selectable pipeline versions; Browserless documents a PDF endpoint that accepts a URL or raw HTML and uses options based on Puppeteer’s PDF options; PDFShift publishes current usage allowances and credit rules. Compare compatibility with your actual HTML, CSS, fonts, and JavaScript, the page-size controls you need, deployment effort, data-handling requirements, and current plan limits. The available documentation does not establish a universal winner for rendering quality or performance.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return an image or PDF. For a screenshot response, it accepts cookie banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. It is not a replacement for a PDF renderer when you need to tune HTML-to-PDF page geometry, but it can skip browser setup for captures. Details and API options are in the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo offers 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up free for 1,000 screenshots a month with no card.
Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
Troubleshooting common scale problems
- Everything looks smaller than expected: Check the PDF paper size, CSS
@page, andpreferCSSPageSizebehavior before increasing scale. The renderer may be fitting content to a different page size than intended. - Text or elements are missing or clipped: Inspect margins and page dimensions, then check print-specific styles and overflow rules. A smaller scale may hide clipping but can make the entire document unreadable.
- The PDF differs from the browser view: Check print media rules first. Puppeteer’s PDF generation uses print CSS by default; screen-oriented styles may not be the rules used for output.
- CSS page size seems ignored: Check whether
preferCSSPageSizeis false. In Puppeteer and Playwright, CSS page size does not take priority by default. - The scale value is rejected or behaves unexpectedly: Confirm the renderer and version, and use that release’s documented option range and naming. Puppeteer documents
0.1through2; do not assume another converter uses the same range. - Tables or line breaks change after scaling: Inspect the result at the intended paper size and verify print CSS, available content width, and margins. Scaling can affect legibility and layout, so validate the actual output rather than relying on an on-screen preview.
Performance, reliability, and cost considerations
Local browser rendering gives you direct control over the browser and PDF options, but your application must operate that rendering setup. A hosted service shifts some infrastructure work to a provider, so evaluate its current limits, pricing, data handling, engine compatibility, and PDF controls for your use case. Documentation establishes that these are distinct approaches, not which will be faster, more reliable, or less expensive for a particular workload. Recheck version-specific browser documentation and service plans before deploying; settings and offerings can change.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsQuick Recap
Best Value
![Doxillion Free Document Converter for Mac – Converts DOCX, DOC, PDF, WPS and Many More Files Quickly [Download]](https://m.media-amazon.com/images/I/51Xjwhv3w2L._SL160_.jpg)
- Convert over 50 document file formats.
- Preview your files from Doxillion before converting them.
- Use batch conversion to convert thousands of files at once.
- Enjoy an easy-to-use, intuitive interface with a Drag and Drop file option.
- Burn your converted or original files directly to disc.
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.
