HTML to PDF Converter

The HTML to PDF Converter turns web pages and HTML strings into PDF documents. It renders the HTML with a Chromium engine that ships inside the NuGet package, so HTML5, CSS3, JavaScript, web fonts and SVG come out as in the Chrome browser, and there is no browser to install on the server. The same component converts HTML to images with the HtmlToImage class.

A conversion takes three steps: create an HtmlToPdf object, optionally set its options, and call one of its methods with a URL or an HTML string. The result is a PDF document in memory or in a file. A new converter already produces an A4 document with the page laid out as in a desktop browser, so the options are needed only to change that result or to add features to the document.

This topic describes the packages, the conversion methods, the page layout and the features of the converter, with links to the topics that describe each of them in detail.

The component is distributed as a NuGet package for each platform. Each package contains the same .NET Standard 2.0 library, used from .NET 6 to .NET 10 and from .NET Framework 4.6.2 to 4.8.1, and the native rendering engine for its platform.

The HiQPdf.Next.Windows and HiQPdf.Next.Linux metapackages reference the HTML to PDF package of their platform together with all the other components of the library. The HiQPdf.Next.HtmlToPdf and HiQPdf.Next metapackages reference both the Windows x64 and the Linux x64 packages, for applications built once and deployed on either platform. Installing and running the packages on each platform is described in Getting Started on Windows, Getting Started on Linux and Getting Started on macOS.

The HtmlToPdf class converts a URL, which can also be a local file, or an HTML string. An HTML string is converted with a base URL, used to resolve the relative URLs of the images, style sheets and scripts it references. The PDF document is returned in a memory buffer or saved to a file:

Each method has an asynchronous variant with the Async suffix, following the Task-based Asynchronous Pattern, with an optional System.ThreadingCancellationToken to cancel the conversion. Converters can run in parallel, one per conversion, as shown in Convert Multiple HTML Pages to PDF in Parallel; how the rendering engine processes are started and reused is described in HTML to PDF Rendering Modes and the Persistent Rendering Engine. The methods and the options of the converter, with the code of the demo, are described in Convert URLs and HTML Strings to PDF.

The size of the PDF pages, the width at which the HTML is laid out and the scale at which it is drawn are set together by a layout method of the converter. A new converter uses FitBrowserWindowToPage(PdfPageSize, PdfPageOrientation, Int32, Boolean) with an A4 page: the page is laid out as in a 1024 pixel browser window and scaled to the page width. HTML templates designed for the paper size use LayoutAtPageWidth(PdfPageSize, PdfPageOrientation, Boolean, String, Double, Boolean), and other methods cover the output of Chrome, receipts and pages as wide as the browser window. The methods and the settings for the usual cases are described in HTML to PDF Page Setup and Scaling.

Beyond the conversion itself, the converter adds structure, interactivity and security to the generated document, and controls how the page is loaded before it is converted.

Page structure

• HTML headers and footers with page numbers, also in browser mode and on a PDF from multiple HTML pages

• HTML stamps on the generated pages

• Page breaks controlled from CSS

• Table headers and footers repeated on each page

• Several HTML pages merged into one PDF document

Navigation and content

• Outlines and internal links and a table of contents created from the HTML

• Selected elements converted or excluded, and the positions of HTML elements in the PDF

• Web fonts embedded in the PDF

Interactivity, standards and security

• PDF forms created from HTML forms, and HTML form values preserved or transferred to another page

• PDF/UA and PDF/A documents for accessibility and archiving

• File attachments and viewer settings

• Passwords and permissions and digital signatures

Loading the page

• HTTP headers, cookies, GET and POST requests and authentication

• The moment of the conversion, for pages that load content asynchronously, and the screen or print media type

Reference

Other Resources