Recursive AI

Vector vs. raster HTML to PDF

Keep text and shapes as vectors for zoom and print. Rasterize the whole page only when a fixed image matters more than selectable text or sharp scaling.

OneRender, a free, open-source .NET library from Recursive AI (MIT or Apache-2.0), lays out and renders HTML and CSS. NuGet · GitHub · Docs

Set up the console project
dotnet new console
dotnet add package RecursiveAI.OneRender.Pdf --version 1.4.0

An all-raster PDF makes sense when you need to preserve a scanned page or a fixed screenshot as an image. Without a separate text layer, its text isn’t selectable. Print quality depends on how many pixels the image has at the printed size. Higher resolution generally needs more image data, but PDF size also depends on the page content and compression; raster isn’t always smaller or larger.

The choice is per item, not per page

OneRender lays out HTML and CSS, then writes the PDF from a list of drawing instructions. Its PDF backend uses native PDF content where it has a direct representation and embeds images where it needs pixels. An effect on one box does not have to turn nearby text into a screenshot.

  • Native PDF content: groups of positioned characters become text with the needed parts of the font embedded; rectangles, rounded boxes, and paths become fills or curves; linear and radial gradients stay smooth color transitions without a bitmap. A conic gradient stays vector but is approximated with 180 wedges.
  • Raster content: source images stay images. Effects such as non-opacity filters, backdrop filters, inline SVG, and blurred shadows can become local images called raster islands. Opacity alone can use native PDF opacity.

Inspect a page that uses both

Use the .NET 10 SDK in an empty directory, then replace the template’s Program.cs with the example. The input has no image assets; it has a heading and a rounded blue box with a blurred shadow.

Program.cs.NET 10
using OneRender.Pdf;
 
const string html = """
    <!doctype html>
    <html lang="en">
    <title>Mixed PDF</title>
    <h1>Quarterly report</h1>
    <div style="width:160px;height:40px;background:#2563eb;
                border-radius:8px;box-shadow:0 3px 12px #0006"></div>
    </html>
    """;
 
using var output = File.Create("mixed.pdf");
var result = HtmlPdf.ToPdf(html, output);
Console.WriteLine($"Pages: {result.PageCount}");
foreach (var diagnostic in result.Diagnostics)
    Console.WriteLine(diagnostic);
Observed outputConsole
Pages: 1

Optional: Use Poppler, a set of command-line tools for reading and inspecting PDFs. Install it with apt install poppler-utils on Debian or Ubuntu, or brew install poppler on macOS, then run:

Inspect mixed.pdfShell
pdftotext -nopgbrk mixed.pdf - | sed '/^$/d'
pdfimages -list mixed.pdf | awk 'NR > 2 {print $3, $4 "x" $5, $13 "x" $14 " ppi"}'
Observed outputPoppler
Quarterly report
image 99x39 48x48 ppi
smask 99x39 48x48 ppi

The heading is extractable text. The image and its smask are the shadow and its alpha mask, not two pictures of the page. No diagnostic was printed: in this release the writer creates the blurred box shadow island without reporting it, so an empty diagnostics list does not prove output is entirely vector.

What resolution changes, and what it does not

RasterDpi defaults to 192 for the PDF output options. It affects raster islands, not text or path resolution. The pinned island limits are 16 million pixels per island and 400 million per document. An oversized island can be drawn at reduced resolution; exceeding the document budget can cause an island to be skipped with a diagnostic. Blurred box shadows are sampled according to the blur, which is why this sample’s shadow is placed at 48 pixels per inch rather than 192.

For zoomable or printable output, spot-check the parts that need to stay sharp, not just the presence of an image in the file. Use text extraction to test whether text survives, inspect vector paths for shapes, and zoom in on the actual effect. If a filtered element must remain vector, simplify or remove the effect and inspect the new PDF.