Click or drag to resize

Fine Control of HTML to PDF Conversion

The converter offers a fine control of the conversion. The default settings suit most pages, and the properties described below change the result when more control is needed.

The sections of this topic:

PDF Document Page Orientation

The PDF pages can be in Portrait or Landscape orientation. By default the page is A4, Portrait. To change the orientation set the PdfPageOrientation property of the converter; a page you add to a document yourself takes its orientation when you create it.

// set the PDF page orientation
pdfConverter.PdfDocumentOptions.PdfPageOrientation = PDFPageOrientation.Landscape;
PDF Document Page Size

The PDF page size can be a standard size like A4, A3 or Letter, or a custom size. The width and height of a custom size are specified in points (1 point is 1/72 inch). See Page size.

// set the PDF page size to standard A4
pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.A4;

// set the PDF page size to a custom value
pdfConverter.PdfDocumentOptions.PdfPageSize = PdfPageSize.Custom;
pdfConverter.PdfDocumentOptions.CustomPdfPageSize = new SizeF(widthInPoints,
    heightInPoints);
The Browser Window of the Converter

The converter renders the HTML page in a browser window of its own, the way a browser renders it on the screen. This window does not depend on the display of the computer: it has a resolution of 96 pixels per inch on every platform, so 96 pixels are 72 points. Web pages measure their elements in pixels, and this is why the window is specified in pixels; it is the only dimension of the converter given in pixels, all the others are in points (1 point is 1/72 inch). The UnitsConverter class converts pixels to points and points to pixels.

The width and height of the window are set with the PageWidth and PageHeight properties, or passed to the PdfConverter constructor.

The default width is 1024 pixels (0 or a negative value also means 1024), which suits most web pages; a page designed for a wider screen may need more. The default height is 0, and the whole page is converted, on as many PDF pages as it needs. A positive height sets the height of the window, which pages sized to the window (for example with CSS vh units) use; with ClipHtmlView set to true the content below that height is left out of the PDF.

PdfConverter pdfConverter = new PdfConverter();
pdfConverter.PageWidth = 1280; // a page designed for a wide screen
pdfConverter.PageHeight = 0; // convert the whole page
HTML Content Resizing in PDF Page

The page is laid out at the width of the browser window and then scaled to the width of the PDF page between the margins. The PDF pages have a fixed size in points: an A4 portrait page is 595 points wide and 842 points high, which is 793 x 1122 pixels at 96 pixels per inch.

At the default width of 1024 pixels, the content of a page is therefore scaled down to fit an A4 page, which is why the fonts and images in the PDF look smaller than in the browser. A window narrower than the page scales the content up. To get the content at its real size, set PageWidth to the width between the margins in pixels - 793 pixels for an A4 portrait page with no margins:

PdfConverter pdfConverter = new PdfConverter();
pdfConverter.PdfDocumentOptions.LeftMargin = 36;
pdfConverter.PdfDocumentOptions.RightMargin = 36;

// the width between the margins of an A4 page, in pixels: the content at real size
pdfConverter.PageWidth = (int)UnitsConverter.PointsToPixels(595 - 36 - 36);

Content wider than the window - a wide table, a long line of preformatted text - is cut at the right edge, as a browser cuts it when it prints. With FitWideContent set to true, a page that lays out wider than the window is laid out again at its own width (at most four times the window width) and the whole page is scaled down to fit, so the wide content appears complete, smaller. A wider page - Landscape orientation, a larger standard size like A3, or a custom size - gives the content more room at the same scale.

Single PDF Page Conversion

With the SinglePage property set to True, the whole HTML content is placed on a single PDF page. The page keeps the width of the specified page size and gets the height needed to show the whole content, with the header and the footer.

pdfConverter.PdfDocumentOptions.SinglePage = true;
Request data, page ranges and content height
  • HttpHeaders and HttpCookies - headers and cookies sent with the requests of the page and of its resources (for example an authentication cookie).

  • HttpPostParameters - form data: when the collection is not empty the page is requested with POST.

  • PageRanges - keep only some pages of the result, for example "1-3,5".

  • AllowContentHeightResize - set it to false when the content is split on more pages than expected.

  • EnableOfflineMode - block every network request, to convert HTML that must not load anything from the network.

PdfConverter converter = new PdfConverter();

// the report page expects the parameters of its search form
converter.HttpPostParameters.Add("year", "2026");
converter.HttpPostParameters.Add("region", "EMEA");
converter.HttpHeaders.Add("Accept-Language", "en-US");

// the first three pages only
converter.PageRanges = "1-3";

converter.SavePdfFromUrlToFile("https://www.example.com/report", "report.pdf");
Timeouts
  • NavigationTimeout - how long the page may take to load, in seconds (default 60).

  • RenderOnTimeout - when the page has not finished loading at the navigation timeout (an image or a script that never answers), convert what is loaded instead of failing. RenderOnTimeout does the same for HTML to image conversions.

  • MaxConversionTime - the time allowed for producing the PDF once the page has loaded, in seconds (default 60); when it is exceeded the conversion fails with a print timeout error. A conversion takes at most NavigationTimeout + MaxConversionTime + 30 seconds, so a page that never finishes - a script in an endless loop - fails in a known time instead of keeping the application waiting.

HtmlToPdfArea, HtmlToPdfElement, HtmlToImageElement and ImgConverter have the same properties.

PdfConverter converter = new PdfConverter();
converter.NavigationTimeout = 30;
// convert the page even if an advertisement never finishes loading
converter.RenderOnTimeout = true;
// give up on a page that takes more than 20 seconds to convert once loaded
converter.MaxConversionTime = 20;
converter.SavePdfFromUrlToFile("https://www.example.com/report", "report.pdf");
Where the last page ends

The library decides where the content ends: ManagedContentTrimming (default true) draws the page the content ends on only down to where the content ends, on a document of any length. A page does not end with a blank page (for example when its bottom margin or padding does not fit on the last page), and LastPageRectangle ends right below the content, where more content can be added to the document. ManagedContentTrimmingMode chooses how the end is found: Ink (the default) measures the painted content, so a shadow or a positioned decoration below the last block is kept; Marker ends where the page layout ends.

With ManagedContentTrimming set to false, the engine shortens the page only when the whole content fits on one page. AllowContentHeightResize set to false turns off both. HTML header and footer areas (HtmlToPdfArea) and HtmlToPdfElement have the same two properties.

PdfConverter converter = new PdfConverter();
converter.ManagedContentTrimmingMode = ManagedContentTrimmingMode.Marker;
Document document = converter.GetPdfDocumentObjectFromUrl(
    "https://www.example.com/invoice");

// add a note right below the converted content
RectangleF last = converter.ConversionSummary.LastPageRectangle;
PdfPage lastPage = document.Pages[converter.ConversionSummary.LastPageIndex];
lastPage.AddElement(new TextElement(0, last.Bottom + 10, "Thank you for your order.",
    document.AddFont(new Font("Arial", 10), true)));
document.Save("invoice.pdf");
document.Close();
See Also