All Components

Dimensions and CSS Units

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

This article explains why the usage of any units other than px—such as 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 screen as being 1cm wide. However, when you query the width in its computed style, you get back 37.78125px. 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 to 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 following result:

37.78125 pt = 37.78125 / 72 in = 1.33 cm

It turns out that you specify that you need 1cm but the actual size on PDF is different from the required dimension and is 1.33cm. 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 because they are not related to CSS or the display resolution.

In this article