---
title: "Vector vs. raster HTML to PDF"
url: https://recursiveai.org/onerender/articles/vector-vs-raster-html-to-pdf/
description: "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."
date: 2026-11-18
author: OneRender team
---

# 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.

November 18, 2026 · OneRender team

OneRender, a free, open-source .NET library from Recursive AI ([MIT](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/LICENSE-MIT) or [Apache-2.0](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/LICENSE-APACHE)), lays out and renders HTML and CSS. [NuGet](https://www.nuget.org/packages/RecursiveAI.OneRender.Pdf/1.4.0) · [GitHub](https://github.com/recursive-ai-oss/onerender-csharp) · [Docs](https://recursiveai.org/onerender/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](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/docs/pdf.md#L24-L42) 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 output · Console*

```
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.pdf · Shell*

```
pdftotext -nopgbrk mixed.pdf - | sed '/^$/d'
pdfimages -list mixed.pdf | awk 'NR > 2 {print $3, $4 "x" $5, $13 "x" $14 " ppi"}'
```

*Observed output · Poppler*

```
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](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/src/OneRender.Pdf/PageEmitter.Leaves.cs#L306-L310), 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](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/docs/pdf.md#L9-L12). It affects raster islands, not text or path resolution. The [pinned island limits](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/docs/pdf.md#L42-L44) 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.
