---
title: "Load local CSS and images for HTML to PDF in C#"
url: https://recursiveai.org/onerender/cookbook/load-html-render-resources/
description: "Supply local CSS and image bytes when rendering HTML to PDF in C#, with an explicit resource allowlist and a missing-image diagnostic."
version: "1.4.0"
---

# Load local CSS and images for HTML to PDF in C#

**OneRender** is a free, open-source HTML and CSS rendering library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneRender.Pdf) · [GitHub](https://github.com/recursive-ai-oss/onerender-csharp) · [Docs](https://recursiveai.org/onerender/docs/) · [Download example (.zip)](https://recursiveai.org/onerender/cookbook/load-html-render-resources/load-html-render-resources.zip)

Resolve relative CSS and image references to bytes you supply; the renderer never fetches them. The input files are in the zip and shown below.

```shell
dotnet add package RecursiveAI.OneRender.Pdf
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

`https://render.example/` is only an identifier for resolving relative URLs, not a server you need to run.

```csharp
using OneRender.Pdf;

using var output = File.Create("card.pdf");
HtmlPdf.ToPdf(File.ReadAllText("input.html"), output,
    new HtmlPdfOptions {
        BaseUrl = "https://render.example/",
        Resources = url => url switch {
            "https://render.example/card.css" => File.ReadAllBytes("card.css"),
            "https://render.example/tile.png" => File.ReadAllBytes("tile.png"),
            _ => null
        }
    });
Console.WriteLine("card.pdf written");
```

```text
card.pdf written
```

Unzip [the example](https://recursiveai.org/onerender/cookbook/load-html-render-resources/load-html-render-resources.zip), then `dotnet run`.

## The full program

`input.html` contains:

```html
<link rel="stylesheet" href="card.css">
<h1>Local resources</h1>
<img src="tile.png" width="32" height="32">
<img src="missing.png" width="32" height="32">
```

`card.css` contains:

```css
body { margin:16px; font:16px sans-serif }
h1 { color:#2563eb }
```

`tile.png` is a 32 × 32 solid blue square (`#2563eb`) included in the download. These sample assets are CC0. `missing.png` is deliberately absent.

```csharp
using OneRender.Pdf;

string html = File.ReadAllText("input.html");
var files = new Dictionary<string, byte[]>
{
    ["https://render.example/card.css"] = File.ReadAllBytes("card.css"),
    ["https://render.example/tile.png"] = File.ReadAllBytes("tile.png")
};
using var output = File.Create("card.pdf");
var result = HtmlPdf.ToPdf(html, output, new HtmlPdfOptions
{
    BaseUrl = "https://render.example/input.html",
    Resources = address => files.GetValueOrDefault(address)
});
Console.WriteLine($"card.pdf: {result.PageCount} page(s)");
foreach (var diagnostic in result.Diagnostics)
    Console.WriteLine($"{diagnostic.Kind}: {diagnostic.Message}");
```

`dotnet run` prints:

```text
card.pdf: 1 page(s)
MissingResource: an image was not supplied by the host
```

An unavailable image records a `MissingResource` diagnostic and paints nothing; it does not stop this PDF from being written.

## Variations

### Supply the missing image

Before creating the output stream in the full program, add this mapping:

```csharp
files["https://render.example/missing.png"] =
    files["https://render.example/tile.png"];
```

The full program then prints:

```text
card.pdf: 1 page(s)
```

## Related recipes

- [Convert HTML to PDF in C#](https://recursiveai.org/onerender/cookbook/html-to-pdf/)
- [Fonts for HTML to PDF in C#](https://recursiveai.org/onerender/cookbook/fonts/)
- [Page headers, footers and page numbers](https://recursiveai.org/onerender/cookbook/paged-media/)

## The short answer

Set `HtmlPdfOptions.BaseUrl` and supply `Resources`, a callback from an absolute address to bytes. Load the CSS and image files you intend to allow, put their bytes in a dictionary, and return `null` for every other address. The HTML is read separately and passed as text to `HtmlPdf.ToPdf`. OneRender does not fetch the HTML or its dependencies for you.

This is useful for an invoice template whose layout and pictures are packaged with your application. The callback maps a reference in the document to a known asset; it is not a general-purpose file loader. The example’s HTTPS address is an identifier used for relative URL resolution, not a server you need to run.

## How to convert HTML to PDF with images?

An image reference needs both markup and bytes. Here `src="tile.png"` resolves against the base address to `https://render.example/tile.png`. That exact key returns the blue tile. The width and height in the markup reserve a square for it. The second image deliberately points to a missing key so you can see the diagnostic instead of mistaking a partially rendered document for a complete one.

The full program prints every returned diagnostic. In this run, the unavailable image produces `MissingResource: an image was not supplied by the host`. The [pinned painting documentation](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/docs/architecture.md#painting) says a missing image paints nothing; it does not draw alt text or a broken-image icon. The PDF can still be written. If your application requires every picture, treat that diagnostic as a reason not to deliver the result.

The variation supplies the absent image under its requested address. It writes the same page count without the missing-resource diagnostic. That is different from merely removing the diagnostic-printing loop: the resource is now actually available.

## How to convert HTML to PDF locally?

Read the HTML, CSS and image files from disk in your own code. Nothing in this example needs a network connection after package restore. Keep relative URL resolution separate from file-system access. A base URL tells the renderer what an address means; it does not grant access to a directory.

The dictionary in the full program is an explicit allowlist. An unexpected reference returns `null`, even if it contains a parent-directory segment or points to another host. Do not replace that mapping with a direct `File.ReadAllBytes` on document-controlled paths. For a larger template, build the dictionary from a trusted asset manifest before rendering.

## How to convert HTML with CSS to PDF?

Supply external stylesheets through the same callback as images. The link to `card.css` becomes an absolute address and the callback returns the stylesheet bytes. Inline styles do not need the callback. The [resource API documentation](https://github.com/recursive-ai-oss/onerender-csharp/blob/d9708ace1863cae70a1b0782b8363ed970e555bb/src/OneRender.Pdf/HtmlPdf.cs) also allows font bytes through this hook.

The PDF path uses print media, so a stylesheet’s print rules may differ from its screen rules. JavaScript is not executed: populate template data and construct the final HTML before calling the renderer. When styling disappears, first check the resolved address and dictionary key, then check the CSS itself. A successful file write does not establish that every requested asset was supplied.
