How to Set PDF Page Size, Margins, and Orientation

Overview

This guide shows how to control page setup with the HTML to PDF API: page size, orientation, margins, scale, backgrounds, CSS media type, and which pages end up in the final PDF. All options are sent in the same request body as your html or url.

Page setup example

The request below renders an A4 portrait PDF with 20mm top and bottom margins and 15mm side margins, keeps background colors, and uses print CSS.

• pageSizeType: A standard paper size.
• orientation: portrait or landscape.
• margin: Page margins for each side.
• printBackground: Whether background colors and images are rendered.
• emulateMediaType: The CSS media type used while rendering.

1curl https://api.pdfgate.com/generate/pdf \2  -X POST \3  -H "Content-Type: application/json" \4  -H "Authorization: Bearer YOUR_API_KEY" \5  --data '{6    "html": "<div style=\"background:#0055d4;color:#fff;padding:16px;\"><h1>Invoice #1042</h1></div><p>Thank you for your order.</p>",7    "pageSizeType": "a4",8    "orientation": "portrait",9    "margin": {10      "top": "20mm",11      "bottom": "20mm",12      "left": "15mm",13      "right": "15mm"14    },15    "printBackground": true,16    "emulateMediaType": "print"17  }' \18  -o output.pdf

Standard page sizes

Set pageSizeTypeto one of the values below. If you don't set it, the PDF is generated as ledger (17 × 11 in), which is wider than it is tall. For most documents you will want to set a4 or letter explicitly.

• a0: 841 × 1189 mm
• a1: 594 × 841 mm
• a2: 420 × 594 mm
• a3: 297 × 420 mm
• a4: 210 × 297 mm
• a5: 148 × 210 mm
• a6: 105 × 148 mm
• letter: 8.5 × 11 in
• legal: 8.5 × 14 in
• tabloid: 11 × 17 in
• ledger: 17 × 11 in (default)

Custom width and height

For non-standard formats such as receipts, labels, or tickets, pass width and height instead of pageSizeType.

• width: Page width in pixels (number).
• height: Page height in pixels (number).

Values are CSS pixels at 96 per inch, so 1mm ≈ 3.78px (for example, A4 is roughly 794 × 1123px). Both fields are required together; sending only one returns a validation error. When both are set, they take precedence and pageSizeType is ignored.

The example below creates an 80mm × 150mm receipt (302 × 567px):

1curl https://api.pdfgate.com/generate/pdf \2  -X POST \3  -H "Content-Type: application/json" \4  -H "Authorization: Bearer YOUR_API_KEY" \5  --data '{6    "html": "<h2>Coffee House</h2><p>1x Espresso ... 2.50</p><p>Total ... 2.50</p>",7    "width": 302,8    "height": 567,9    "margin": {10      "top": "4mm",11      "bottom": "4mm",12      "left": "4mm",13      "right": "4mm"14    }15  }' \16  -o receipt.pdf

The page size always comes from the API request. A CSS @page { size: ... } rule in your HTML does not change it.

Orientation

orientation accepts portrait (default) or landscape. landscape swaps the page width and height, and it does this for custom width/height too. When you use custom dimensions, set them in the shape you want and leave orientation out.

The default ledger size is already wide, so ledger with landscape gives you a tall 11 × 17 in page.

Margins

margin is an object with optional top, bottom, left, and right fields. Each value is a string with a unit: px, mm, cm, or in (for example "20mm" or "0.5in"). A value without a unit is read as pixels. Any side you leave out has a margin of 0, so content runs to the edge of the page unless you set margins or add padding in your HTML.

Margins with headers and footers

The header and footertemplates are drawn inside the top and bottom margins. That's why a header requires margin.top and a footer requires margin.bottom; the API returns an error if they are missing.

• If the header is taller than margin.top, it gets clipped. Increase the margin instead of shrinking the header.
• Page content always starts below the top margin, so a bigger margin moves the body down and leaves more room for the header.
• Add horizontal padding to the templates so they line up with your left and right margins.

See How to Add Headers and Footers to PDFs for templates, page numbers, and styling.

Scale wide layouts

scale zooms the rendered content without changing the page size or margins. The default is 1 and accepted values are 0.1 to 2; anything outside that range returns a validation error.

Use a value below 1 when a wide layout (dashboards, wide tables, fixed-width pages) is cut off on the right or wraps badly. 0.7–0.9 is usually enough. Combining it with landscape gives you even more horizontal room.

1curl https://api.pdfgate.com/generate/pdf \2  -X POST \3  -H "Content-Type: application/json" \4  -H "Authorization: Bearer YOUR_API_KEY" \5  --data '{6    "url": "https://en.wikipedia.org/wiki/PDF",7    "pageSizeType": "a4",8    "orientation": "landscape",9    "scale": 0.8,10    "emulateMediaType": "screen",11    "pageRanges": "1-3"12  }' \13  -o output.pdf

Background colors and images

Browsers leave out CSS background colors and images when printing unless told otherwise. PDFGate sets printBackground to true by default, so backgrounds are included. Set it to false for a lighter, ink-friendly PDF.

If backgrounds are still missing, the page's own print stylesheet is usually the cause: many sites and CSS frameworks remove backgrounds inside @media print. Render with emulateMediaType: "screen", or override the rule with the css parameter. Header and footer templates have their own rule; see background colors in headers and footers.

Print vs screen media

emulateMediaType decides which CSS rules apply while the page is rendered:

• print: Rules inside @media print apply, like when you print from a browser.
• screen: The page renders as it does in a browser window and print rules are ignored.

If you don't set it, url requests render with screen and html requests render with print.

This is the most common reason a PDF doesn't match what you see in the browser. If a site's print stylesheet hides navigation, changes fonts, or strips colors, use screen. If you control the HTML, print lets you keep PDF-only styles in @media print:

1@media print {2  nav, .cookie-banner, .no-print {3    display: none;4  }56  body {7    font-size: 12pt;8  }9}

Page ranges

pageRanges keeps only the listed pages in the final PDF. Pages are numbered from 1, and the value is a string of page numbers and ranges separated by commas, without spaces: "1-3", "2", or "1-3,5,7-9". If you don't set it, all pages are included.

Page breaks

Where pages break is controlled by CSS in your HTML (break-before, break-inside, and similar), not by an API parameter. See HTML to PDF page breaks for the details.

Additional notes

Page size, orientation, margins, and scale work the same for html and url requests. Only the default emulateMediaType differs.

If content still doesn't fit, check for fixed widths in your CSS (for example width: 1200px). Relative widths reflow to the page size; fixed widths need scale or a larger page.

For a full list of supported options, see the HTML to PDF API Reference.