PDF Export Configuration
This article covers the options that define the page setup of the exported PDF file—the basic PDFOptions, how to scale the content, and how CSS units map to PDF units.
The Drawing library provides options for specifying the basic parameters of the generated PDF file.
| Option | Description | Default |
|---|---|---|
paperSize | A paper format (for example, A4), an array of two numbers for the width and height of the paper, or "auto" to size the paper just enough to accommodate the drawing. | "auto" |
margin | The paper margins—an object with top, left, right, and bottom numbers. When paperSize is "auto", the dimensions expand to include the margin. | None |
landscape | Rotates the paper dimensions so that the width corresponds to the longer side of the output file. | false |
multiPage | Enables multiple-page output. For a detailed walkthrough, see Multi-Page Content. | false |
date | The date on which the document is created. | new Date() |
title,
author,
subject,
keywords,
creator
| Optional strings included in the PDF information dictionary. | None |
The paperSize property accepts the standard formats A0–A10, B0–B10, C0–C10, Executive, Folio, Legal, Letter, and Tabloid. Numbers are treated as typographic points (1/72 of an inch), and you can also use unit strings such as "297mm" with the mm, cm, in, or pt units. The same units apply to margin.
Scaling the Drawings
The Drawing library enables you to export a PDF document that is bigger or smaller than its original elements.
Scaling is convenient when you generate a multi-page PDF with automatic page breaking. Because the original dimensions usually look too big in PDF, you can specify a suitable scale factor to get a better output for print. To scale the content, use the scale option.
Scaling affects only the content—the output paper size and page margins remain the same. However, scaling still affects the position of the headers and footers of page templates.
For more information on how to scale the content with the PDF Export component, refer to its documentation.
The following example demonstrates how to set a scale factor of 0.8 and keep an A4 page size and a two-centimeter page margin.
Dimensions and CSS Units
Set all your dimensions in
px. Values incm,in,mm, orptlead to unpredictable results in the exported PDF.
To draw the DOM, the module inspects the computed styles of the elements, and the browser always returns computed styles in pixels. For example, a <div style="width: 1cm"> element renders on screen as exactly 1cm wide when the dots-per-inch (DPI) setting is correctly detected. However, when you query its computed style, you get back a value such as 37.78125px, which can vary depending on the display.
Because the computed style yields pixels, the PDF generator keeps a 1:1 mapping between screen pixels and the default PDF unit, the typographic point (pt). As a result, the same element renders in the PDF with a length of 37.78125pt. Two constants define the relationship between these units:
1 pt = 1/72 in(points to inches)1 in = 2.54 cm(inches to centimeters)
Combined, these constants produce 37.78125 pt = 37.78125 / 72 in ≈ 1.33 cm. This means that although you specify a dimension of 1cm in your CSS, the exported PDF renders it as 1.33cm—not the value you intended.
To get a predictable layout in PDF, convert your dimensions to pixels before you apply them by using the following formulas. The paperSize and margin options are exceptions to this behavior—because they are neither related to CSS nor to the display resolution, you can use any of the supported unit types with them.
| Source unit | Formula | Approximate factor |
|---|---|---|
Centimeters (cm) | N cm = N * 28.346 px | 72 / 2.54 ≈ 28.346 |
Inches (in) | N in = N * 72 px | 72 |