Click or drag to resize
Pdf Library for .NET

Resizing Content During Conversion with Select.Pdf Html to Pdf Converter

Html pages that are converted to pdf and pdf pages in the generated document usually do not have the same size. Because of that, Select.Pdf Library needs to perform some operations on the content rendered from the web page to be able to display it in the pdf page.

The rendering engines do not all handle the web page size the same way. The differences are listed with each property below. The engine is selected with RenderingEngine.

Pdf Page Size

The size of the pdf pages can be specified using PdfPageSize property of the HtmlToPdfOptions object. More details about this in the following section: Setting Pdf Page Properties.

Web Page Size

Select.Pdf Html to Pdf Converter has an internal browser that renders the web page just like a regular browser. There are some properties that control how the web page will look in the internal browser:

  • WebPageWidth - Gets or sets the width of the converted web page as it would appear in the internal browser used to render the html.

    The web page width is specified in pixels and the default value is 1024px. The web page is laid out the way a browser window this wide lays it out.

    Content wider than this width is handled differently by each engine:

    • WebKit - the internal browser is made wider to fit the whole content, which is then scaled down to fit the pdf page (with the default AutoFitWidth). When WebPageFixedSize is true, the width is kept and the content that does not fit is cut off on the right.

    • WebKit Restricted - the whole content is scaled down to fit the pdf page, whether the size is fixed or not.

    • Blink and Chromium - the content is scaled down to fit the pdf page, up to one and a half times the web page width (1536px for the default width). Content wider than that is cut off on the right, whether the size is fixed or not. To convert wider content, set a larger web page width.

    If WebPageWidth is set to 0, the WebKit and WebKit Restricted engines determine the width from the html content. The Blink and Chromium engines use the default width of 1024px.

    This property can also be set directly in the constructor of HtmlToPdf class.

  • WebPageHeight - Gets or sets the height of the converted web page as it would appear in the internal browser used to render the html.

    The web page height is specified in pixels and the default value is 0px. The height does not limit what is converted: the whole web page is converted and flows onto as many pdf pages as it needs. To leave out the content below this height, set WebPageFixedSize to true as well.

    It is the height of the browser window the web page is loaded in: the height scripts on the page see (window.innerHeight), and what decides which parts of the page count as visible while it loads. What the default value (0) means depends on the engine:

    • Chromium - the window is as tall as the pdf page content area at the web page width (1449px for an A4 page at the default width), so scripts, lazily loaded images and content revealed on scroll work without setting a height. CSS viewport units such as 100vh are resolved against the pdf page, whatever the height. When ManagedContentTrimming is false, the window has almost no height instead, and the notes for the WebKit engines below apply.

    • Blink - the window is one pdf page tall while the web page loads. Content sized with CSS viewport units (for example a 100vh cover) does not print reliably with this engine, with or without a height set: it can print shorter than the page, or push the content that follows it onto a new page. Use the Chromium engine for such pages.

    • WebKit and WebKit Restricted - the window has almost no height. Content that a script sizes from the window height, or that is sized with CSS viewport units, can be missing from the generated pdf. For such pages set a height, for example 768.

    Frames: with the default height, the WebKit and WebKit Restricted engines can leave out or cut the content of an iframe sized to the height of the page, and the Blink engine can also leave out the content of a frameset. Set a height for such pages. The Chromium engine converts them with the default height.

    Content that loads as it is scrolled into view is also controlled by LazyImagesLoadingEnabled and LazyImagesLoadingDelay (Blink and Chromium engines).

    This property can also be set directly in the constructor of HtmlToPdf class.

  • WebPageFixedSize - Controls whether the content below WebPageHeight is left out of the generated pdf document.

    The default value of this property is false. If it is set to true, the web page is converted only down to WebPageHeight pixels, and the content below that height is not included. With the WebKit engine the width is fixed as well, and content wider than WebPageWidth is cut off. The other engines handle the width the same way whether the size is fixed or not.

    A fixed size taller than the space available on the pdf page is spread over as many pages as it needs - it is not squeezed onto a single page. With the Blink and Chromium engines every page but the last is a full page and the last one is cut at the height asked for: the content below it is removed from the document, not hidden, and bookmarks, mapped web elements, links and internal destinations follow the same height. A line of text is never cut - when one crosses that height, the last page ends above it. These engines also move a line that crosses the bottom of a page onto the next page, so a fixed size spanning several pdf pages can end up to one line short of the height asked for at each page boundary it crosses. The WebKit engines cut exactly at the height.

    Note: WebPageFixedSize needs a page height set with WebPageHeight - there is no size to fix the browser at otherwise. With the default value (0) the WebKit engines fail (they cannot render a web page with no height) and the Blink and Chromium engines ignore this property.

Content Resizing

Because a web page has generally a different width compared with a standard pdf page, the content will not fit perfectly when the web page content is rendered into pdf. As an example, most web sites are optimized for browsers with page widths of at least 1024px or 1280px. A standard A4 page has 595 x 842 points. 1 point is 1/72 inch. 1 pixel is 1/96 inch. This means that an A4 page width is 793px. Because the web page width (1024px or more) is larger than this pdf page width, when the content is rendered into pdf, it will either get truncated or it needs to be resized (shrunk) to fit the pdf page width.

The WebKit Restricted, Blink and Chromium engines always scale the web page so that its width fits the pdf page content width (the page width minus the left and right margins). A smaller WebPageWidth therefore produces larger content in the pdf, and a larger value produces smaller content. Content that is taller than one pdf page flows onto additional pages.

The WebKit engine has a few more properties that control how the content from the web page is resized during the rendering into the pdf document. The other engines ignore them:

  • AutoFitWidth - Specifies the html content horizontal auto fit mode.

    The converter considers both AutoFitWidth and AutoFitHeight when the html content is rendered in the pdf page or specified rectangle.

    If this property is set to NoAdjustment, the html content is not resized horizontally in any way to fit the available space. If the content is larger, it will be cut and not all of it will be displayed in the generated pdf file.

    If this property is set to ShrinkOnly, the html content is resized only if the content width is larger than the destination space (pdf page or rectangle) width. In this case, the content is shrunk to fit the destination space width and the elements that it contains (texts, images) will appear smaller in the generated pdf document than in the original web page. If the original content width is smaller than the destination width, no adjustments will be done and the content will be rendered exactly as it is, even though some additional white space might appear to its right.

    If this property is set to AutoFit, the html content is resized to fit the available width of the destination space. If the original content width is smaller than the destination width, the elements rendered (texts, images) will appear larger in the generated pdf document. If the original content width is larger than the destination width, the elements rendered (texts, images) will appear smaller in the generated pdf document.

    The default value of this property is ShrinkOnly.

  • AutoFitHeight - Specifies the html content vertical auto fit mode.

    The converter considers both AutoFitWidth and AutoFitHeight when the html content is rendered in the pdf page or specified rectangle.

    If this property is set to NoAdjustment, the html content is not resized vertically in any way to fit the available space. If the content is larger, it flows onto additional pdf pages.

    If this property is set to ShrinkOnly, the html content is resized only if the content height is larger than the destination space (pdf page or rectangle) height. In this case, the content is shrunk to fit the destination space height and the elements that it contains (texts, images) will appear smaller in the generated pdf document than in the original web page. If the original content height is smaller than the destination height, no adjustments will be done and the content will be rendered exactly as it is, even though some additional white space might appear at the bottom.

    If this property is set to AutoFit, the converter will treat it like ShrinkOnly.

    The default value of this property is NoAdjustment and for rendering, the converter will only take AutoFitWidth into consideration.

Sample Code

The following sample code shows the simplest code that can be used to convert an url to pdf:

C#
VB
Copy 
                  // instantiate a html to pdf converter object
HtmlToPdf converter = new HtmlToPdf();

// create a new pdf document converting an url
PdfDocument doc = converter.ConvertUrl(url);

The above code is equivalent with the following sample code where the default values are explicitly specified:

C#
VB
Copy 
                  // instantiate a html to pdf converter object
HtmlToPdf converter = new HtmlToPdf();

// set converter options
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;

converter.Options.WebPageWidth = 1024;
converter.Options.WebPageHeight = 0;
converter.Options.WebPageFixedSize  = false;

converter.Options.AutoFitWidth = HtmlToPdfPageFitMode.ShrinkOnly;
converter.Options.AutoFitHeight = HtmlToPdfPageFitMode.NoAdjustment;

// create a new pdf document converting an url
PdfDocument doc = converter.ConvertUrl(url);