SelectPdf.HtmlToPdf.Universal 26.5.0

SelectPdf HTML to PDF Converter for .NET — Community Edition (FREE), Cross-Platform

The Community Edition is the free version of the HTML to PDF converter found in the full SelectPdf library. It is free for personal and commercial use and offers most of the professional converter's features — the main limitation is that it generates PDF documents up to 5 pages long.

The converter is built on Chromium (HTML5, CSS3, web fonts, modern JavaScript) and is cross-platform: it runs on Windows (x64, x86), Linux (x64, ARM64) and macOS (Apple Silicon), on .NET 10, .NET 9, .NET 8 and .NET Standard 2.0 (consumable from .NET Framework 4.6.1+), in Docker containers and on Microsoft Azure, Amazon Web Services and Google Cloud. Verified with the .NET 11 release candidate (RC 1) on Windows x64, Linux x64 and ARM64, and macOS.

The Community Edition is a drop-in subset of the full library: both use the SelectPdf.Universal namespace, so moving up to the full SelectPdf.Universal package needs no code change.

Installation

dotnet add package SelectPdf.HtmlToPdf.Universal
# engine: win-x64, win-x86, linux-x64, linux-arm64 or osx-arm64
dotnet add package SelectPdf.Universal.Native.win-x64

The managed SelectPdf.HtmlToPdf.Universal package is AnyCPU (the assembly is SelectPdf.HtmlToPdf.Universal.dll). Add the SelectPdf.Universal.Native.<rid> package that matches your runtime to deploy the Chromium engine next to your application: win-x64 for a 64-bit Windows process, win-x86 for a 32-bit one, linux-x64, linux-arm64 (glibc 2.30+) or osx-arm64 (macOS 13+).

For an application that runs on one platform, one package installs both: SelectPdf.HtmlToPdf.Windows (Windows x64), SelectPdf.HtmlToPdf.Linux, SelectPdf.HtmlToPdf.Linux.Arm64 or SelectPdf.HtmlToPdf.MacOS. Reference one of them or the two packages above, not both.

Quick start

using SelectPdf.Universal;

HtmlToPdf converter = new HtmlToPdf();
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
converter.Options.MarginTop = 20;
converter.Options.MarginBottom = 20;

using PdfDocument doc = converter.ConvertUrl("https://selectpdf.com");
// or: converter.ConvertHtmlString("<h1>Hello</h1>", baseUrl);
doc.Save("page.pdf");

Asynchronous conversion

HtmlToPdf converter = new HtmlToPdf();
using PdfDocument doc = await converter.ConvertUrlAsync(
    "https://selectpdf.com", cancellationToken);
doc.Save("page.pdf");

HTML to PDF in an ASP.NET Core endpoint

using SelectPdf.Universal;

var app = WebApplication.CreateBuilder(args).Build();

// POST an HTML string, get a PDF back
app.MapPost("/pdf", async (HttpRequest request) =>
{
    string html = await new StreamReader(request.Body).ReadToEndAsync();

    HtmlToPdf converter = new HtmlToPdf();
    converter.Options.PdfPageSize = PdfPageSize.A4;
    using PdfDocument doc = await converter.ConvertHtmlStringAsync(html);
    byte[] pdf = doc.Save();

    return Results.File(pdf, "application/pdf", "document.pdf");
});

app.Run();

Headers, footers, security and archiving

HtmlToPdf converter = new HtmlToPdf();

converter.Options.DisplayFooter = true;
converter.Footer.Height = 30;
PdfTextSection pageNumbers = new PdfTextSection(0, 10,
    "Page: {page_number} of {total_pages}",
    PdfFont.CreateStandardFont(PdfStandardFont.Helvetica, 8));
pageNumbers.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNumbers);

// AES-256 by default
converter.Options.SecurityOptions.OwnerPassword = "owner";
converter.Options.SecurityOptions.CanCopyContent = false;

// or PDF/A-1b to PDF/A-4, PDF/X-1a
converter.Options.PdfStandard = PdfStandard.PdfA2B;

using PdfDocument doc = converter.ConvertUrl("https://selectpdf.com");
doc.Save("page.pdf");

Main Features

• Generate PDF documents up to 5 pages; when a document is longer, ConversionResult.PdfPageCountBeforeLimit reports how many pages it had
• Convert any web page or raw HTML string to PDF, synchronously or asynchronously with cancellation
• Page settings (size, orientation, margins); resize content to fit the page
• Document properties, viewer preferences, security (passwords, permissions, AES-256 encryption)
• PDF/A-1b, PDF/A-2b, PDF/A-3b, PDF/A-3u, PDF/A-4, PDF/A-4e, PDF/A-4f and PDF/X-1a output
• Custom headers and footers, including HTML in headers and footers, with page numbering
• Automatic and manual page breaks; repeat HTML table headers on each page
• Support for @media screen and print
• Internal and external links; automatic bookmarks from HTML elements
• HTTP headers, cookies, POST data, authentication, login forms, proxy servers
• Conversion delay, navigation timeout, lazy image loading, custom CSS, post-loading scripts
• Enable/disable JavaScript; HTML5 / CSS3 / web fonts support
• Up to 8 conversions run concurrently

The full SelectPdf.Universal package adds, among others: output beyond 5 pages, PDF creation and editing (text, images, HTML and shapes on pages), loading and modifying existing PDFs, Word to PDF, HTML to image, redaction, digital signatures and signature validation, form filling, PDF portfolios, tagged PDF/UA and PDF/A-3a output, ZUGFeRD / Factur-X invoices, single-page PDF, partial page conversion, PDF to text and PDF to image.

Docker

The Linux engine packages bundle the Chromium libraries, so a Docker image needs no apt-get lines. Reference SelectPdf.Universal.Native.linux-x64 (or linux-arm64 for an ARM64 image) and build with the official .NET images:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "YourApp.dll"]

Reference one engine package per build: the packages install into the same folder, so a project that develops on Windows and deploys to Linux picks the package by runtime, for example with a Condition on $(RuntimeIdentifier).

Deployment notes

• Linux: the native packages bundle the Chromium shared libraries, so conversions run on minimal distributions and in containers without apt-get. Requires glibc 2.30+ (Debian 11+, Ubuntu 20.04+, RHEL 9+). Alpine (musl) is supported through the remote engine: reference SelectPdf.HtmlToPdf.Universal alone and set RenderingEngine.ChromiumRemote.
• Docker: the official .NET images work as they are on Linux; Windows containers need Windows Server Core with the core Windows fonts installed.
• Cloud: step-by-step guides for Azure App Service, Azure Functions (Dedicated and Premium plans), Azure Container Apps, AWS Lambda (container image, x64 and arm64), AWS Elastic Beanstalk and Google Cloud Run.
• Fonts: Linux hosts and container images often have no fonts, and the fonts built into the library cover Latin scripts only. Add SelectPdf.Universal.Fonts (Noto fonts for every script, copied next to the application on Linux and macOS) to render every language; your own fonts go in a fonts folder next to the application, on every platform.
• Engine hosting: the Chromium engine runs inside your application when the native package matches your process architecture (a 32-bit Windows process, such as a default Windows App Service worker, uses win-x86); with another package, conversions run in a separate engine process automatically. Set GlobalProperties.ChromiumEngineHostMode = ChromiumEngineHostMode.OutOfProcess to run every conversion in its own engine process.
• Native debug symbols: SkiaSharp 3.119.2 and later ship libSkiaSharp.pdb (about 250 MB for the Windows architectures) as runtime files, which the application never uses (SkiaSharp #3519). This package leaves them out of your build and publish output and your .deps.json; set <SelectPdfKeepNativeSymbols>true</SelectPdfKeepNativeSymbols> in your project to keep them.

Migrating to SelectPdf.HtmlToPdf.Universal

SelectPdf.HtmlToPdf.Universal is the cross-platform successor of the Windows-only Select.HtmlToPdf / Select.HtmlToPdf.NetCore packages. It keeps their classes and members, so porting is mostly mechanical:

1. Replace the Select.HtmlToPdf* package references (and the Chromium / Blink companion packages) with SelectPdf.HtmlToPdf.Universal plus a SelectPdf.Universal.Native.<rid> package, and remove Select.Html.dep and the old engine folders from the project.
2. Change using SelectPdf; to using SelectPdf.Universal;.
3. Replace System.Drawing types: PdfColor for colors, SelectPdf.Universal.Drawing for points, rectangles and sizes, PdfFont / PdfSystemFont for fonts.
4. HTML is rendered with Chromium only: remove WebKit / Blink engine selection and settings, rename CefEnginePath to ChromiumEnginePath, and review the output of pages that rendered with the WebKit default.
5. HtmlToImage is part of the full SelectPdf.Universal package.

The documentation's Migrating to SelectPdf.HtmlToPdf.Universal topic lists every change, the defaults that differ and how fonts are found on each platform.

Moving from DinkToPdf or WkHtmlToPdfDotNet

SelectPdf.Compat.DinkToPdf and SelectPdf.Compat.WkHtmlToPdfDotNet keep the API of those wkhtmltopdf wrappers and render with this package instead.

Documentation & Support

• Documentation: https://selectpdf.com/html-to-pdf/docs/
• Community Edition: https://selectpdf.com/community-edition/
• Website: https://selectpdf.com/