HTML to PDF Page Setup and Scaling

The layout methods of the HtmlToPdfConverter class decide three things: the size of the PDF page, the width at which the HTML is laid out and the scale at which the layout is drawn on the page. Each method covers one kind of document; you call it, convert, and the converter computes the layout width and the scale from the page size, the orientation and the margins in use when the PDF is generated.

This topic describes the methods, their parameters and their effect, then the settings for the usual cases, and at the end the properties the methods work with, for readers who set them one by one. The options are also listed in HTML To PDF Converter Options. If you are moving an integration from EvoPdf Classic, read Migrate HTML to PDF Page Setup and Headers from EvoPdf Classic as well.

A new converter is in the layout of FitBrowserWindowToPage(PdfPageSize, PdfPageOrientation, Int32) with its default arguments: an A4 page with the page as a desktop browser shows it, scaled to the page width. Calling another method replaces that layout.

The rule is short: call one layout method, then change the page size, the orientation, the margins and any other option freely, before or after the call. The converter applies the layout with the values in use when the PDF is generated. Set the zoom or the browser window width only when you want to control them yourself: that replaces the values the layout computes.

How each option behaves when it is set after a layout method is listed at the end of this topic, in Options Set After a Layout Method.

The layout in use can be read from LayoutMethod, a PageLayoutMethod value: the last layout method called, or Manual after the zoom or the viewer width was set. A new converter reports FitBrowserWindowToPage.

FitBrowserWindowToPage

For web pages: the page is laid out as a browser of the given width shows it and the result is scaled to the page. The parameters are the page size, the orientation (portrait by default) and the width of the browser window in pixels: 1024 for the desktop layout of a page, 412 for its phone layout, a larger value for a page with wide fixed content. The scale follows from the page and the window; on A4 without margins a 1024 pixel window is drawn at 77.47 percent.

// A4 portrait, the desktop layout of the page scaled to the page width: the settings of a new converter
converter.FitBrowserWindowToPage(PdfPageSize.A4);

// Letter landscape, a 1280 pixel window
converter.FitBrowserWindowToPage(PdfPageSize.Letter, PdfPageOrientation.Landscape, 1280);

LayoutAtPageWidth

For HTML designed for the paper size, like invoices and reports: the HTML is laid out at the width of the page and drawn without scaling, so a 16 px font is 12 points and a 700 px wide table is 525 points wide. The parameters are the page size, the orientation, whether a @page size rule in the HTML sets the page size (false by default) and the CSS media type, screen by default like the other layouts; pass "print" for a template whose print style sheet must apply. A web page converted this way gets the layout it has at the width of the page, which for most CSS frameworks is the tablet layout.

// An invoice template designed for A4
converter.LayoutAtPageWidth(PdfPageSize.A4);

// A template whose @page rule sets the paper size
converter.LayoutAtPageWidth(PdfPageSize.A4, PdfPageOrientation.Portrait, preferCssPageSize: true);

// A template with a print style sheet
converter.LayoutAtPageWidth(PdfPageSize.A4, PdfPageOrientation.Portrait, mediaType: "print");

// A web page laid out at the width of a landscape page
converter.LayoutAtPageWidth(PdfPageSize.A4, PdfPageOrientation.Landscape);

PrintLikeChrome

The output of the Save as PDF command of the Chrome browser: the print media type, margins of 1 cm on each side and no background colors or images. The parameters are the page size and the orientation. Use it when the PDF must match what the users of the page get when they print it themselves. The margins and PrintBackgrounds can be changed after the call; for example, setting PrintBackgrounds to true keeps the background colors and images, like the Background graphics option of Chrome.

converter.PrintLikeChrome(PdfPageSize.Letter);

SinglePageOfWidth

One page of a fixed width, as tall as the content, for receipts and tickets. The parameters are the page width and the margin on each side, in points: 227 points is 80 mm paper, 164 points is 58 mm paper. The content is laid out at the width left between the margins and drawn without scaling. Give the width and the margins as arguments: margins set after the call are added to the page width.

// A receipt for 80 mm paper, 5 mm margins
converter.SinglePageOfWidth(227, 14);

PageWidthFromBrowserWindow

The PDF page takes the width of the browser window, one pixel being 0.75 points, and the HTML is drawn exactly as the browser shows it, without scaling. The parameters are the window width in pixels and whether the whole page goes on one PDF page, as tall as the content. The page height comes from the page size and the orientation otherwise. Use it for a pixel exact copy of a page, or for a screenshot like PDF on one page.

// A 768 point wide page (1024 pixels), the content drawn 1:1, paginated at the A4 height
converter.PageWidthFromBrowserWindow();

// The whole page on one PDF page
converter.PageWidthFromBrowserWindow(1024, singlePage: true);

The HTML is laid out in CSS pixels at 96 DPI and the PDF page is measured in points, 1/72 of an inch: one pixel is 0.75 points and one point is 1.333 pixels. An A4 page is 595 points, or 793 pixels, wide; the margins, in points, are subtracted before the HTML is laid out.

HtmlViewerZoom is the scale at which the layout is drawn, in percent. It works like the zoom of a browser when it prints: at a lower zoom more content fits on a line and everything is smaller, at a higher zoom less content fits and everything is larger. CSS media queries and viewport units see the zoomed layout width, so a responsive page shows the layout that matches it. The methods compute the zoom; you read it from the property, and you set it only to override them. Values from 10 to 200 are supported, with decimals.

Before it is printed, the page is loaded in a browser window of HtmlViewerWidth by HtmlViewerHeight pixels, 1024 by 2048 by default, where its scripts run and the lazy loaded images visible in it are requested. The methods keep the window width equal to the layout width, so scripts that size charts or tables from the window produce elements that fit the printed layout. The window height matters only for pages that load content when it scrolls into view, handled by LoadLazyImages and AutoResizeHtmlViewerHeight, and for the single page layouts, where the page is at least as tall as the window.

A page can be wider than the width it is laid out at: a table or a container with a fixed width in pixels, an image that does not shrink, a wide preformatted block. What happens then is automatic and cannot be turned off:

• If the content is at most 1.5 times wider than the layout width, the whole page is scaled down so that the widest element fits. A 1000 px wide table on an A4 page (793 px) is 1.26 times too wide, so the page is drawn at 79 percent and a 16 px font comes out at 9.5 points instead of 12.

• If the content is more than 1.5 times wider, the page is scaled down by 1.5 and what still does not fit is cut off at the right edge. A 1400 px wide table on A4 loses its last 210 pixels.

The width that counts is the rendered width, which includes the default 8 px margin of the body element on each side. To avoid the scaling, give the layout the width the content needs: a wider browser window in FitBrowserWindowToPage, 1400 pixels for a 1400 px table, which the method then draws at the zoom that fits it on the page; or the exact width with PageWidthFromBrowserWindow(1400), on a page as wide as the content.

PdfDocumentOptionsAutoResizePdfPageHeight makes the page as tall as the rendered content, so the whole page ends up on one PDF page. The page width comes from the page size in the fixed page layouts, or from the viewer width when the page follows the browser window. If the viewer height is larger than the content the page keeps the viewer height, so for short pages set a small HtmlViewerHeight. A page break forced from CSS still starts a new PDF page.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// The page width follows the viewer width, the page height follows the content
converter.PageWidthFromBrowserWindow(1024, singlePage: true);

byte[] pdf = converter.ConvertUrl(url);

// The same settings made one by one
converter.HtmlViewerWidth = 1024;
converter.PdfDocumentOptions.AutoResizePdfPageWidth = true;
converter.PdfDocumentOptions.AutoResizePdfPageHeight = true;

For one page with the width of an A4 sheet, set the viewer width to 794 pixels: 794 × 0.75 is 595 points, the width of A4.

The margins set with LeftMargin, RightMargin, TopMargin and BottomMargin are 0 by default. They are the margins of every page unless the HTML itself declares margins in a @page rule. A page with @page { margin: 2cm } is printed with 2 cm margins whatever the code sets, the same way a browser gives the page rule priority over its own default margins. To use the margins from your code with such a page, remove the margin declaration from the page rule.

A @page rule can also declare a page size. By default, PreferCssPageSize is false and the PDF page keeps the size set in code. The page declared in CSS is laid out at its own size. If it is larger than the PDF page it is scaled down and centered. If it is smaller it is centered without scaling. With PreferCssPageSize = true the size declared in CSS becomes the size of the PDF page and the value of PdfPageSize is used only for pages without a declared size. A size: landscape declaration changes the orientation in both cases.

The MediaType property selects the CSS media type, screen by default, so the page is styled as it appears in the browser window. Set it to print to apply the @media print rules of the page, which usually hide navigation and adjust colors. Two features apply the print media rules on their own, because they need them: RepeatTableHeaderFooter and a header or footer hidden on some pages with ReserveSpaceAlways set to false. Background colors and images are printed by default and can be turned off with PrintBackgrounds. Page breaks are controlled from CSS; see Insert Page Breaks in PDF Using CSS in HTML and Avoid Page Breaks Inside HTML Elements Using CSS.

An HTML header or footer set with PdfHtmlHeader or PdfHtmlFooter is drawn in the top or bottom margin of the page, across the full page width. When AutoResizePdfMargins is true, the default, the top margin is set to the height of the header and the bottom margin to the height of the footer, replacing the values set in code. To leave space between the header and the content, or between the edge of the page and the header, use the Margins of the header template: they are part of the header height. With AutoResizePdfMargins = false the margins from code stay as they are and the header must fit in the top margin you set.

The header and footer reduce the height available to the content on each page and leave the layout width unchanged in every layout. Their HTML is laid out and drawn at the zoom of the document, so a font size has the same size in the header, in the footer and in the page, and the page numbers follow it. Everything about the header and footer templates is in Add HTML in Header and Footer with Page Numbers. For the built-in browser headers, enabled with EnableHeaderFooter, the top and bottom margins must be set large enough to hold the templates; see Add HTML in Header and Footer Using Browser Mode.

Each case starts with the layout method that covers it, followed by the settings the method makes, for readers who set them one by one or need a variation. The methods change only the properties listed; everything not shown keeps its default value.

A Web Page on A4 or Letter with Its Desktop Layout

A responsive site laid out at 793 pixels shows its tablet layout. To print the desktop layout on a standard page, fix the page size and lower the zoom until the layout width reaches the desktop breakpoint. FitBrowserWindowToPage does the arithmetic: on A4 it lays the page out at 1024 pixels and draws it at 77.47 percent, close to what a browser does when it prints a wide page, and keeps the viewer at the same 1024 pixels so that the page loads at the width it is printed at.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// A4 portrait page, the 1024 pixel browser window scaled to it
converter.FitBrowserWindowToPage(PdfPageSize.A4);

byte[] pdf = converter.ConvertUrl("https://www.evopdf.com");

// The same settings made one by one
converter.PdfDocumentOptions.AutoResizePdfPageWidth = false;
converter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
converter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Portrait;
// Lay the page out at 793 / 0.7747 = 1024 pixels and draw it at 77.47 percent
converter.HtmlViewerZoom = 77.47;
converter.HtmlViewerWidth = 1024;

The zoom depends on the page size, the margins and the layout width you want; the method computes it as the content width in pixels divided by the window width. The table gives the values for a 1024 pixel window.

An HTML Template Designed for the Paper Size

Invoices, contracts and reports are usually written for a known paper size: a container of 210 mm or 794 pixels, font sizes in points, page breaks placed with CSS and often a print style sheet. Such a template wants a fixed page and no zoom; LayoutAtPageWidth sets both and the viewer width equal to the content width, so that the template is measured at the width it was designed for. Pass "print" as the media type when the template has a print style sheet.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// Margins in points; a @page rule in the template overrides them
converter.PdfDocumentOptions.LeftMargin = 36;
converter.PdfDocumentOptions.RightMargin = 36;
converter.PdfDocumentOptions.TopMargin = 36;
converter.PdfDocumentOptions.BottomMargin = 36;

// The exact page size, the template laid out at the page width with its print style sheet;
// preferCssPageSize lets a @page { size } rule in the template decide the page size
converter.LayoutAtPageWidth(PdfPageSize.A4, PdfPageOrientation.Portrait, preferCssPageSize: true, mediaType: "print");

byte[] pdf = converter.ConvertHtml(invoiceHtml, baseUrl);

// The same settings made one by one
converter.PdfDocumentOptions.AutoResizePdfPageWidth = false;
converter.PdfDocumentOptions.AutoResizePdfPageHeight = false;
converter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
converter.MediaType = "print";
// Viewer width equal to the content width: (595 - 72) * 4 / 3 = 697 pixels
converter.HtmlViewerWidth = 697;
converter.PdfDocumentOptions.PreferCssPageSize = true;

An HTML Page Converted at Its Exact Pixel Size

A dashboard, an email or a page built at a fixed pixel width, for example 1000 pixels, comes out at 1:1 with PageWidthFromBrowserWindow: the browser window gets the width of the page and the PDF page takes that width. This is also the right choice for a snapshot of a page that will be viewed on screen rather than printed.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// The page width follows a 1000 pixel window: 1000 * 0.75 = 750 points
converter.PageWidthFromBrowserWindow(1000);

// A4 height for each page; PageWidthFromBrowserWindow(1000, singlePage: true) gives one page instead
converter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;

byte[] pdf = converter.ConvertUrl(url);

// The same settings made one by one
converter.PdfDocumentOptions.AutoResizePdfPageWidth = true;
converter.HtmlViewerWidth = 1000;

A Wide Table on a Landscape Page

A landscape A4 page has 1123 pixels of content width, enough for most tables built for a 1024 pixel screen without any zoom. Lay the page out at the page width in landscape; for a table built for 1280 pixels, fit a 1280 pixel window to the page instead.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// A4 landscape, the HTML laid out at its 1123 pixel content width
converter.LayoutAtPageWidth(PdfPageSize.A4, PdfPageOrientation.Landscape);

// A table built for 1280 pixels: a 1280 pixel window scaled to the page, zoom 87.73
// converter.FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Landscape, 1280);

byte[] pdf = converter.ConvertUrl(url);

The Same Output as Save as PDF in Chrome

Some pages are checked against the PDF that Chrome itself produces from the print dialog. Chrome prints with the print media type, margins of 1 cm on each side and no background colors or images. PrintLikeChrome makes exactly these settings.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

converter.PrintLikeChrome(PdfPageSize.A4);

byte[] pdf = converter.ConvertUrl(url);

// The same settings made one by one
converter.PdfDocumentOptions.AutoResizePdfPageWidth = false;
converter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
// Chrome prints with 1 cm margins, print media type and no backgrounds
converter.PdfDocumentOptions.LeftMargin = 28;
converter.PdfDocumentOptions.RightMargin = 28;
converter.PdfDocumentOptions.TopMargin = 28;
converter.PdfDocumentOptions.BottomMargin = 28;
converter.MediaType = "print";
converter.PdfDocumentOptions.PrintBackgrounds = false;
// Viewer width equal to the content width: (595 - 56) * 4 / 3 = 719 pixels
converter.HtmlViewerWidth = 719;

A Page in Its Mobile Layout

A zoom above 100 lays the page out narrower than the content width and enlarges the result to fill the page. Fitting a 412 pixel window, the width of a phone screen, to an A4 page lays the page out at 412 pixels and draws it at 192.56 percent, so the page shows its mobile layout, enlarged to the page width. The zoom stops at 200, so the narrowest layout on A4 is 397 pixels; a narrower window is widened to that. This is a way to check the mobile version of a site or to print an email built for phones.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// A phone window of 412 pixels enlarged to an A4 page
converter.FitBrowserWindowToPage(PdfPageSize.A4, PdfPageOrientation.Portrait, 412);

byte[] pdf = converter.ConvertUrl(url);

// The same settings made one by one
converter.PdfDocumentOptions.AutoResizePdfPageWidth = false;
converter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;
// Lay the page out at 793 / 1.9256 = 412 pixels and draw it at 192.56 percent
converter.HtmlViewerZoom = 192.56;
converter.HtmlViewerWidth = 412;

A Receipt on One Page of Fixed Width

Receipts and tickets need one page of a fixed width (80 mm, or 227 points, for a typical receipt printer) that is as tall as the content. SinglePageOfWidth takes the width and the margin in points. The page takes the width of the browser window, which the method sets to the content width in pixels, 265 for 227 points minus two 14 point margins, and a viewer height of 1 keeps the page from being taller than the content.

HtmlToPdfConverter converter = new HtmlToPdfConverter();

// One page 227 points (80 mm) wide with 14 point (5 mm) margins, as tall as the content
converter.SinglePageOfWidth(227, 14);

byte[] pdf = converter.ConvertHtml(receiptHtml, baseUrl);

// The same settings made one by one: 5 mm margins are 14 points
converter.PdfDocumentOptions.LeftMargin = 14;
converter.PdfDocumentOptions.RightMargin = 14;
converter.PdfDocumentOptions.TopMargin = 14;
converter.PdfDocumentOptions.BottomMargin = 14;
converter.PdfDocumentOptions.AutoResizePdfPageWidth = true;
converter.PdfDocumentOptions.AutoResizePdfPageHeight = true;
converter.HtmlViewerWidth = 265;
converter.HtmlViewerHeight = 1;

A layout method sets a group of options and chooses how the zoom and the browser window width are obtained. FitBrowserWindowToPage, LayoutAtPageWidth and PrintLikeChrome let the converter compute these two values when the PDF is generated, from the page size, the orientation and the margins in use at that moment. PageWidthFromBrowserWindow and SinglePageOfWidth set them to fixed values. The table shows what happens when an option is set after the call.

// A4 landscape in the default layout, with margins set after the call:
// the zoom is computed for the landscape page and the margins
converter.FitBrowserWindowToPage(PdfPageSize.A4);
converter.PdfDocumentOptions.PdfPageOrientation = PdfPageOrientation.Landscape;
converter.PdfDocumentOptions.LeftMargin = 36;
converter.PdfDocumentOptions.RightMargin = 36;

// Setting the zoom ends the automatic layout: the page is laid out for zoom 90, whatever its size
converter.HtmlViewerZoom = 90;

Reference

Other Resources