Dimensions and CSS Units

To ensure the proper rendering of dimensions and CSS units in PDF, use the px unit.

The usage of units other than px (cm, in, mm, or pt) leads to unpredictable results. To draw the DOM, the module inspects the computed styles of the elements. At this stage, all dimensions are converted to pixels. For example, if you take <div style='width: 1cm'> and if the dots-per-inch (DPI) setting is correctly displayed, this element is rendered by the browser on the screen as being 1cm wide. However, when you query the width in its computed style, you get back a 37.78125px value. This value might vary depending on the display.

For simplicity and because the computed style yields back pixels, the PDF generator keeps a 1:1 mapping between the screen pixels and the default PDF unit, which is the typographic point (pt). This means that the same element will be rendered in PDF with a length of 37.78125pt. The conversion rules for these units are:

  • 1 pt = 1/72 in (points to inches)
  • 1 in = 2.54 cm (inches to centimeters)

If you put them together, you get the 37.78125 pt = 37.78125 / 72 in = 1.33 cm result. This means that you can specify the dimension to 1cm, but the actual in PDF is 1.33cm, which is different from the required. To get a predictable layout in PDF, apply pixels to set all your dimensions. To calculate the values, use the following rules:

  • N cm = N * 28.346 px (72 / 2.54 ≈ 28.346)
  • N in = N * 72 px

The paperSize and margin options that you pass are exceptions from this behavior and you can use all unit types, as they are neither related to CSS nor to the display resolution.

In this article

Not finding the help you need?