How to Use Base URLs & Asset Encoding in C# .NET 10

Q: What is the purpose of using Base URLs in IronPDF?

Base URLs in IronPDF are used to specify the location of CSS, JavaScript, and image assets during HTML to PDF conversion, ensuring these assets are properly loaded by providing a `BaseUrlOrPath` parameter.

Q: How can I implement base URLs in a basic scenario using IronPDF?

You can implement base URLs by setting the `BaseUrlOrPath` parameter in IronPDF's HTML to PDF generation code. This enables smooth asset loading and ensures all CSS, JavaScript, and images are correctly referenced during the conversion process.

Q: Why might my image assets not be loading correctly in my PDF?

If image assets are not loading correctly, ensure absolute paths are used, check file permissions, test with remote URLs, and enable logging for debugging. IronPDF also provides custom options like `BaseUrlOrPath` to accurately reference asset locations.

Q: How do I set different base URLs for PDF headers and main content in IronPDF?

In IronPDF, you can configure different base URLs for headers, footers, and main content by using the `HtmlHeaderFooter` class to set distinct `BaseUrl` properties for each section.

Q: What should I be aware of when using `CustomCssUrl` in IronPDF?

`CustomCssUrl` is used when rendering HTML strings to PDFs. It allows you to specify additional stylesheets for better PDF rendering and is ideal for print-specific styles, PDF layout optimization, and conditional formatting.

Q: When should I use Base64 encoding for images in IronPDF?

Base64 encoding is useful for embedding images directly into HTML content to avoid external dependency issues, enhance compatibility across platforms, and increase reliability in production environments without accessing the file system.

Q: How does Base64 encoding affect the size of my PDFs?

Base64 encoding increases HTML and subsequently PDF size due to data being represented in a larger format. Use it for smaller images, while larger assets should use external references to optimize PDF size.

Q: What are the benefits of using Base64 encoding in IronPDF?

Base64 encoding benefits include creating self-contained HTML, ensuring cross-platform compatibility, reducing security risks by eliminating file system access, and preventing missing asset errors in live environments.

Q: How do I handle relative asset paths in HTML files for PDF conversion in IronPDF?

Ensure your file structure supports the relative paths in your HTML file, and use `RenderHtmlFileAsPdf` from IronPDF to convert HTML files to PDFs while correctly loading CSS and JavaScript resources.

Q: Why don't headers and footers in IronPDF inherit Base URLs from the main document?

Headers and footers in IronPDF do not inherit Base URLs from the main document to maintain styling independence, ensure consistent rendering, and allow flexible asset organization for optimal PDF creation.

Curtis Chau

Updated: August 2, 2026

Base URLs in IronPDF allow CSS, JavaScript, and image assets to be properly loaded during HTML to PDF conversion by specifying the BaseUrlOrPath parameter, which can be a web URL or local file path for relative asset resolution.

Quickstart: Implement Base URLs in IronPDF

Get started with IronPDF by implementing base URLs for smooth asset loading during HTML to PDF conversion in .NET C#. This example demonstrates how to set the BaseUrlOrPath to ensure all CSS, JavaScript, and images are properly referenced, simplifying PDF generation with minimal setup.

1Install IronPDF with NuGet Package Manager
PM > Install-Package IronPdf
```
Install-Package IronPdf
```

2Copy and run this code snippet.

new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf("<img src='icons/logo.png'>", @"C:\site\assets\").SaveAs("with-assets.pdf");

new IronPdf.ChromePdfRenderer().RenderHtmlAsPdf("<img src='icons/logo.png'>", @"C:\site\assets\").SaveAs("with-assets.pdf");

3Deploy to test on your live environment

Start using IronPDF in your project today with a free trial

Minimal Workflow (5 steps)

Download IronPDF for HTML to CSS to Image Support
Specify BaseUrlOrPath parameter for external images in HTML
Configure correct src in MVC for web and PDF display
Specify custom headers and footers using the BaseUrl property
Check the output PDF

Convert.ToBase64String

How Do I Render PDFs from HTML Strings with Image and CSS Assets?

When converting HTML strings to PDF, set a BaseUrlOrPath parameter for assets such as CSS, JavaScript files, and images. The BaseUrlOrPath specifies the base URL from which all assets load relative to. CustomCssUrl

This can be a web URL starting with 'http' to load remote assets or a local file path to access assets on disk. Setting the BaseUrlOrPath correctly ensures assets load properly during conversion. For more details on HTML to PDF conversion, check our comprehensive HTML to PDF tutorial.

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

string baseUrl = @"C:\site\assets\";
string html = "<img src='icons/iron.png'>";

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html, baseUrl);

// Export PDF
pdf.SaveAs("html-with-assets.pdf");

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

string baseUrl = @"C:\site\assets\";
string html = "<img src='icons/iron.png'>";

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html, baseUrl);

// Export PDF
pdf.SaveAs("html-with-assets.pdf");

Dim renderer As New ChromePdfRenderer()

Dim baseUrl As String = "C:\site\assets\"
Dim html As String = "<img src='icons/iron.png'>"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, baseUrl)

pdf.SaveAs("html-with-assets.pdf")

Dim renderer As New ChromePdfRenderer()

Dim baseUrl As String = "C:\site\assets\"
Dim html As String = "<img src='icons/iron.png'>"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, baseUrl)

pdf.SaveAs("html-with-assets.pdf")

For complex scenarios involving external assets, explore our guide on managing fonts or adding images to PDFs.

How Do I Configure Base URLs in MVC Applications?

In MVC applications, specifying image file paths requires careful configuration. To ensure IronPDF finds images and displays them correctly on the website, configure the baseUrl and HTML src="" attribute properly.

With the file hierarchy shown below set

baseUrlOrPath to @"wwwroot/image"
src attribute to "../image/Sample.jpg"

wwwroot
└── image
    ├── Sample.jpg
    └── Sample.png

wwwroot
└── image
    ├── Sample.jpg
    └── Sample.png

Text

For example:

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("html.Result", @"wwwroot/image");

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("html.Result", @"wwwroot/image");

' Instantiate ChromePdfRenderer
Dim renderer As New ChromePdfRenderer()

' Render HTML to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("html.Result", "wwwroot/image")

' Instantiate ChromePdfRenderer
Dim renderer As New ChromePdfRenderer()

' Render HTML to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("html.Result", "wwwroot/image")

<!-- Correct image references for MVC -->
<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>

<!-- Correct image references for MVC -->
<img src="../image/Sample.jpg"/>
<img src="../image/Sample.png"/>

HTML

For ASP.NET Core MVC specific implementations, refer to our CSHTML to PDF (MVC Core) guide.

Which File Path Formats Should I Avoid?

Warning: #### File Path Formats That Do Not Work These formats work in Chrome browser but point to wrong directories in MVC apps. They work with IronPDF if baseUrlOrPath is provided in the RenderHtmlAsPdf method:

<img src="image/footer.png"/>  
<img src="./image/footer.png"/>

<img src="image/footer.png"/>  
<img src="./image/footer.png"/>

HTML

These formats work with MVC apps but fail with IronPDF file paths:

<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>

<img src="/image/footer.png"/>  
<img src="~/image/footer.png"/>

HTML

What Are Common Troubleshooting Tips for Asset Loading?

When assets fail to load, consider these troubleshooting steps:

Verify absolute paths: Use absolute file paths during development to confirm accessibility
Check file permissions: Ensure the application has read access to asset directories
Test with remote URLs: Use fully qualified URLs to isolate path issues
Enable logging: Use IronPDF's custom logging to debug asset loading

// Example: Debug asset loading with absolute paths
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Enable debug logging
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(500); // Give assets time to load

// Use absolute path for testing
string absoluteBasePath = Path.GetFullPath(@"C:\MyProject\wwwroot\assets");
string html = @"
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>";

PdfDocument pdf = renderer.RenderHtmlAsPdf(html, absoluteBasePath);

// Example: Debug asset loading with absolute paths
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Enable debug logging
renderer.RenderingOptions.EnableJavaScript = true;
renderer.RenderingOptions.WaitFor.RenderDelay(500); // Give assets time to load

// Use absolute path for testing
string absoluteBasePath = Path.GetFullPath(@"C:\MyProject\wwwroot\assets");
string html = @"
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>";

PdfDocument pdf = renderer.RenderHtmlAsPdf(html, absoluteBasePath);

Imports System.IO

' Example: Debug asset loading with absolute paths
Dim renderer As New ChromePdfRenderer()

' Enable debug logging
renderer.RenderingOptions.EnableJavaScript = True
renderer.RenderingOptions.WaitFor.RenderDelay(500) ' Give assets time to load

' Use absolute path for testing
Dim absoluteBasePath As String = Path.GetFullPath("C:\MyProject\wwwroot\assets")
Dim html As String = "
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, absoluteBasePath)

Imports System.IO

' Example: Debug asset loading with absolute paths
Dim renderer As New ChromePdfRenderer()

' Enable debug logging
renderer.RenderingOptions.EnableJavaScript = True
renderer.RenderingOptions.WaitFor.RenderDelay(500) ' Give assets time to load

' Use absolute path for testing
Dim absoluteBasePath As String = Path.GetFullPath("C:\MyProject\wwwroot\assets")
Dim html As String = "
    <html>
    <head>
        <link rel='stylesheet' href='styles/main.css'>
    </head>
    <body>
        <img src='images/logo.png' />
        <script src='scripts/app.js'></script>
    </body>
    </html>"

Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, absoluteBasePath)

How Do I Add HTML Headers and Footers with Images?

When rendering HTML headers and footers to new or existing PDFs, they're treated as standalone HTML documents and don't inherit the BaseURL from the PDF. For comprehensive header and footer options, see our headers and footers guide.

Set a BaseURL from which assets may load: ChromePdfRenderOptions

Why Don't Headers Inherit Base URLs from the Main Document?

Headers and footers render as separate HTML documents for performance and isolation. This design allows:

Independent styling without affecting main content
Consistent rendering across all pages
Better memory management for large documents
Flexibility to use different asset sources

How Do I Set Different Base URLs for Headers vs Content?

Specify different base URLs for headers, footers, and main content to organize assets effectively:

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Main content base URL
string contentBaseUrl = @"C:\website\public\";

// Header specific assets
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    BaseUrl = new Uri(@"C:\website\headers\").AbsoluteUri
};

// Footer specific assets
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    BaseUrl = new Uri(@"C:\website\footers\").AbsoluteUri
};

// Render main content with its own base URL
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl);

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Main content base URL
string contentBaseUrl = @"C:\website\public\";

// Header specific assets
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
    HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    BaseUrl = new Uri(@"C:\website\headers\").AbsoluteUri
};

// Footer specific assets
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
    HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    BaseUrl = new Uri(@"C:\website\footers\").AbsoluteUri
};

// Render main content with its own base URL
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl);

Dim renderer As New ChromePdfRenderer()

' Main content base URL
Dim contentBaseUrl As String = "C:\website\public\"

' Header specific assets
renderer.RenderingOptions.HtmlHeader = New HtmlHeaderFooter() With {
    .HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    .BaseUrl = New Uri("C:\website\headers\").AbsoluteUri
}

' Footer specific assets
renderer.RenderingOptions.HtmlFooter = New HtmlHeaderFooter() With {
    .HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    .BaseUrl = New Uri("C:\website\footers\").AbsoluteUri
}

' Render main content with its own base URL
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl)

Dim renderer As New ChromePdfRenderer()

' Main content base URL
Dim contentBaseUrl As String = "C:\website\public\"

' Header specific assets
renderer.RenderingOptions.HtmlHeader = New HtmlHeaderFooter() With {
    .HtmlFragment = "<img src='header-logo.png'><link rel='stylesheet' href='header.css'>",
    .BaseUrl = New Uri("C:\website\headers\").AbsoluteUri
}

' Footer specific assets
renderer.RenderingOptions.HtmlFooter = New HtmlHeaderFooter() With {
    .HtmlFragment = "<div class='footer'>© 2024 Company</div><link rel='stylesheet' href='footer.css'>",
    .BaseUrl = New Uri("C:\website\footers\").AbsoluteUri
}

' Render main content with its own base URL
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Main Content</h1>", contentBaseUrl)

My favorite library of this kind is IronPDF. It allows for fast and efficient manipulation of PDF files. It also has many valuable features, like exporting to PDF/A format and digitally signing PDF documents.

Milan Jovanovic

Microsoft MVP

View case study

IronOCR means we can save $40,000 annually from manual processing, while enhancing productivity and freeing up resources for high-impact tasks. I would highly recommend it.

Brent Matzelle

Chief Technology Officer, OPYN

View case study

How Do I Convert HTML Files to PDF with Local Assets?

When rendering HTML files to PDF, all assets are assumed local to that file. Learn more about converting HTML files in our HTML File to PDF guide.

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlFileAsPdf("C:\\Assets\\TestInvoice1.html");

// Export PDF
pdf.SaveAs("Invoice.pdf");

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlFileAsPdf("C:\\Assets\\TestInvoice1.html");

// Export PDF
pdf.SaveAs("Invoice.pdf");

Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Render HTML file to PDF
Private pdf As PdfDocument = renderer.RenderHtmlFileAsPdf("C:\Assets\TestInvoice1.html")

' Export PDF
pdf.SaveAs("Invoice.pdf")

Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Render HTML file to PDF
Private pdf As PdfDocument = renderer.RenderHtmlFileAsPdf("C:\Assets\TestInvoice1.html")

' Export PDF
pdf.SaveAs("Invoice.pdf")

In the above example, all JS, CSS and image files load from the C:\Assets folder on disk - the same directory as the HTML file.

For convenience, use CustomCssUrl in HtmlToPdf for Additional Stylesheets to specify an additional stylesheet used only for .NET PDF rendering if desired. For example:

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css";

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export PDF
pdf.SaveAs("tryCss.pdf");

using IronPdf;

// Instantiate ChromePdfRenderer
ChromePdfRenderer renderer = new ChromePdfRenderer();

// Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css";

// Render HTML file to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>");

// Export PDF
pdf.SaveAs("tryCss.pdf");

Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css"

' Render HTML file to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")

' Export PDF
pdf.SaveAs("tryCss.pdf")

Imports IronPdf

' Instantiate ChromePdfRenderer
Private renderer As New ChromePdfRenderer()

' Set additional CSS url
renderer.RenderingOptions.CustomCssUrl = "./style.css"

' Render HTML file to PDF
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Hello World</h1>")

' Export PDF
pdf.SaveAs("tryCss.pdf")

CustomCssUrl

Please note: The ChromePdfRenderOptions.CustomCssUrl property currently only functions when rendering from HTML strings to PDFs using the RenderHtmlAsPdf method

When Should I Use CustomCssUrl for Additional Styling?

CustomCssUrl is ideal for:

Print-specific styles: Hide navigation menus or interactive elements
PDF layout optimization: Adjust margins and page breaks for print
Conditional formatting: Apply styles only when generating PDFs
A/B testing: Test different PDF layouts without modifying source HTML

How Do I Handle Relative Asset Paths in HTML Files?

When working with HTML files containing relative paths, ensure your file structure supports the references:

// Example HTML file structure
/*
C:\Projects\Reports\
    ├── invoice.html
    ├── css\
    │   └── styles.css
    ├── js\
    │   └── calculations.js
    └── images\
        └── logo.png
*/

// HTML content with relative paths
string htmlContent = @"
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>";

// Save HTML and render
File.WriteAllText(@"C:\Projects\Reports\invoice.html", htmlContent);
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlFileAsPdf(@"C:\Projects\Reports\invoice.html");
pdf.SaveAs("invoice-output.pdf");

// Example HTML file structure
/*
C:\Projects\Reports\
    ├── invoice.html
    ├── css\
    │   └── styles.css
    ├── js\
    │   └── calculations.js
    └── images\
        └── logo.png
*/

// HTML content with relative paths
string htmlContent = @"
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>";

// Save HTML and render
File.WriteAllText(@"C:\Projects\Reports\invoice.html", htmlContent);
ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlFileAsPdf(@"C:\Projects\Reports\invoice.html");
pdf.SaveAs("invoice-output.pdf");

Imports System.IO
Imports IronPdf

' Example HTML file structure
'
' C:\Projects\Reports\
'     ├── invoice.html
'     ├── css\
'     │   └── styles.css
'     ├── js\
'     │   └── calculations.js
'     └── images\
'         └── logo.png
'

' HTML content with relative paths
Dim htmlContent As String = "
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>"

' Save HTML and render
File.WriteAllText("C:\Projects\Reports\invoice.html", htmlContent)
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlFileAsPdf("C:\Projects\Reports\invoice.html")
pdf.SaveAs("invoice-output.pdf")

Imports System.IO
Imports IronPdf

' Example HTML file structure
'
' C:\Projects\Reports\
'     ├── invoice.html
'     ├── css\
'     │   └── styles.css
'     ├── js\
'     │   └── calculations.js
'     └── images\
'         └── logo.png
'

' HTML content with relative paths
Dim htmlContent As String = "
<!DOCTYPE html>
<html>
<head>
    <link rel='stylesheet' href='css/styles.css'>
    <script src='js/calculations.js'></script>
</head>
<body>
    <img src='images/logo.png' alt='Company Logo'>
    <h1>Invoice #12345</h1>
</body>
</html>"

' Save HTML and render
File.WriteAllText("C:\Projects\Reports\invoice.html", htmlContent)
Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlFileAsPdf("C:\Projects\Reports\invoice.html")
pdf.SaveAs("invoice-output.pdf")

How Do I Encode Images Directly in HTML Using Base64?

Image assets can be encoded directly into HTML files or strings, avoiding issues with missing images. Use base64 encoding for this approach. Use base64 encoding for this approach. Use base64 encoding for this approach:

First obtain the binary data of the image by reading the file or receiving it through a network request.
Use the Convert.ToBase64String method in Microsoft .NET to convert binary data to base64.
Construct the image tag in HTML using "data:image/svg+xml;base64," before the base64 data. Note that the image type is specified before the base64 data. Visit the MDN Web Docs on Image Types and Formats for more information on image format types.

using IronPdf;
using System;
using System.IO;

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Import image file binary data
byte[] binaryData = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg");

// Convert the binary data to base 64
string imgDataUri = Convert.ToBase64String(binaryData);

// Embed in HTML
string html = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>";

// Convert HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html);

// Export the PDF
pdf.SaveAs("embedImageBase64.pdf");

using IronPdf;
using System;
using System.IO;

ChromePdfRenderer renderer = new ChromePdfRenderer();

// Import image file binary data
byte[] binaryData = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg");

// Convert the binary data to base 64
string imgDataUri = Convert.ToBase64String(binaryData);

// Embed in HTML
string html = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>";

// Convert HTML to PDF
PdfDocument pdf = renderer.RenderHtmlAsPdf(html);

// Export the PDF
pdf.SaveAs("embedImageBase64.pdf");

Imports IronPdf
Imports System
Imports System.IO

Private renderer As New ChromePdfRenderer()

' Import image file binary data
Private binaryData() As Byte = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg")

' Convert the binary data to base 64
Private imgDataUri As String = Convert.ToBase64String(binaryData)

' Embed in HTML
Private html As String = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>"

' Convert HTML to PDF
Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html)

' Export the PDF
pdf.SaveAs("embedImageBase64.pdf")

Imports IronPdf
Imports System
Imports System.IO

Private renderer As New ChromePdfRenderer()

' Import image file binary data
Private binaryData() As Byte = File.ReadAllBytes("ironpdf-logo-text-dotnet.svg")

' Convert the binary data to base 64
Private imgDataUri As String = Convert.ToBase64String(binaryData)

' Embed in HTML
Private html As String = $"<img src='data:image/svg+xml;base64,{imgDataUri}'>"

' Convert HTML to PDF
Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html)

' Export the PDF
pdf.SaveAs("embedImageBase64.pdf")

Why Would I Choose Base64 Encoding Over File References?

Base64 encoding offers several advantages:

Self-contained HTML: No external dependencies, simplifying distribution
Cross-platform compatibility: Works regardless of file system differences
Security: No file system access required, reducing security risks
Reliability: Eliminates missing asset errors in production
Version control: Images are part in HTML, simplifying versioning

However, consider these trade-offs:

Increased HTML size: Base64 encoding increases size by approximately 33%
No caching: Embedded images can't be cached separately
Memory usage: Entire image must load in memory

What Image Formats Work Best with Base64 Encoding?

Different image formats have varying efficiency when base64 encoded:

// Example: Encoding different image formats
public string EncodeImageWithMimeType(string imagePath)
{
    byte[] imageBytes = File.ReadAllBytes(imagePath);
    string base64 = Convert.ToBase64String(imageBytes);
    
    // Determine MIME type based on extension
    string extension = Path.GetExtension(imagePath).ToLower();
    string mimeType = extension switch
    {
        ".png" => "image/png",      // Best for graphics with transparency
        ".jpg" or ".jpeg" => "image/jpeg",  // Best for photographs
        ".gif" => "image/gif",       // Best for simple animations
        ".svg" => "image/svg+xml",   // Best for scalable graphics
        ".webp" => "image/webp",     // Best overall compression
        _ => "image/png"             // Default fallback
    };
    
    return $"data:{mimeType};base64,{base64}";
}

// Usage
string encodedImage = EncodeImageWithMimeType("logo.png");
string html = $"<img src='{encodedImage}' alt='Company Logo'>";

// Example: Encoding different image formats
public string EncodeImageWithMimeType(string imagePath)
{
    byte[] imageBytes = File.ReadAllBytes(imagePath);
    string base64 = Convert.ToBase64String(imageBytes);
    
    // Determine MIME type based on extension
    string extension = Path.GetExtension(imagePath).ToLower();
    string mimeType = extension switch
    {
        ".png" => "image/png",      // Best for graphics with transparency
        ".jpg" or ".jpeg" => "image/jpeg",  // Best for photographs
        ".gif" => "image/gif",       // Best for simple animations
        ".svg" => "image/svg+xml",   // Best for scalable graphics
        ".webp" => "image/webp",     // Best overall compression
        _ => "image/png"             // Default fallback
    };
    
    return $"data:{mimeType};base64,{base64}";
}

// Usage
string encodedImage = EncodeImageWithMimeType("logo.png");
string html = $"<img src='{encodedImage}' alt='Company Logo'>";

' Example: Encoding different image formats
Public Function EncodeImageWithMimeType(imagePath As String) As String
    Dim imageBytes As Byte() = File.ReadAllBytes(imagePath)
    Dim base64 As String = Convert.ToBase64String(imageBytes)
    
    ' Determine MIME type based on extension
    Dim extension As String = Path.GetExtension(imagePath).ToLower()
    Dim mimeType As String = If(extension, {
        ".png", "image/png",        ' Best for graphics with transparency
        ".jpg", "image/jpeg",       ' Best for photographs
        ".jpeg", "image/jpeg",      ' Best for photographs
        ".gif", "image/gif",        ' Best for simple animations
        ".svg", "image/svg+xml",    ' Best for scalable graphics
        ".webp", "image/webp"       ' Best overall compression
    }, "image/png")                ' Default fallback
    
    Return $"data:{mimeType};base64,{base64}"
End Function

' Usage
Dim encodedImage As String = EncodeImageWithMimeType("logo.png")
Dim html As String = $"<img src='{encodedImage}' alt='Company Logo'>"

' Example: Encoding different image formats
Public Function EncodeImageWithMimeType(imagePath As String) As String
    Dim imageBytes As Byte() = File.ReadAllBytes(imagePath)
    Dim base64 As String = Convert.ToBase64String(imageBytes)
    
    ' Determine MIME type based on extension
    Dim extension As String = Path.GetExtension(imagePath).ToLower()
    Dim mimeType As String = If(extension, {
        ".png", "image/png",        ' Best for graphics with transparency
        ".jpg", "image/jpeg",       ' Best for photographs
        ".jpeg", "image/jpeg",      ' Best for photographs
        ".gif", "image/gif",        ' Best for simple animations
        ".svg", "image/svg+xml",    ' Best for scalable graphics
        ".webp", "image/webp"       ' Best overall compression
    }, "image/png")                ' Default fallback
    
    Return $"data:{mimeType};base64,{base64}"
End Function

' Usage
Dim encodedImage As String = EncodeImageWithMimeType("logo.png")
Dim html As String = $"<img src='{encodedImage}' alt='Company Logo'>"

How Does Base64 Encoding Impact PDF File Size?

Base64 encoding affects PDF size in predictable ways:

// Comparison example
public void CompareFileSizes()
{
    ChromePdfRenderer renderer = new ChromePdfRenderer();
    
    // Method 1: External image reference
    string htmlExternal = "<img src='large-photo.jpg'>";
    PdfDocument pdfExternal = renderer.RenderHtmlAsPdf(htmlExternal, @"C:\images\");
    
    // Method 2: Base64 encoded image
    byte[] imageBytes = File.ReadAllBytes(@"C:\images\large-photo.jpg");
    string base64Image = Convert.ToBase64String(imageBytes);
    string htmlBase64 = $"<img src='data:image/jpeg;base64,{base64Image}'>";
    PdfDocument pdfBase64 = renderer.RenderHtmlAsPdf(htmlBase64);
    
    // Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length / 1024} KB");
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length / 1024} KB");
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length / 1024} KB");
}

// Comparison example
public void CompareFileSizes()
{
    ChromePdfRenderer renderer = new ChromePdfRenderer();
    
    // Method 1: External image reference
    string htmlExternal = "<img src='large-photo.jpg'>";
    PdfDocument pdfExternal = renderer.RenderHtmlAsPdf(htmlExternal, @"C:\images\");
    
    // Method 2: Base64 encoded image
    byte[] imageBytes = File.ReadAllBytes(@"C:\images\large-photo.jpg");
    string base64Image = Convert.ToBase64String(imageBytes);
    string htmlBase64 = $"<img src='data:image/jpeg;base64,{base64Image}'>";
    PdfDocument pdfBase64 = renderer.RenderHtmlAsPdf(htmlBase64);
    
    // Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length / 1024} KB");
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length / 1024} KB");
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length / 1024} KB");
}

' Comparison example
Public Sub CompareFileSizes()
    Dim renderer As New ChromePdfRenderer()

    ' Method 1: External image reference
    Dim htmlExternal As String = "<img src='large-photo.jpg'>"
    Dim pdfExternal As PdfDocument = renderer.RenderHtmlAsPdf(htmlExternal, "C:\images\")

    ' Method 2: Base64 encoded image
    Dim imageBytes As Byte() = File.ReadAllBytes("C:\images\large-photo.jpg")
    Dim base64Image As String = Convert.ToBase64String(imageBytes)
    Dim htmlBase64 As String = $"<img src='data:image/jpeg;base64,{base64Image}'>"
    Dim pdfBase64 As PdfDocument = renderer.RenderHtmlAsPdf(htmlBase64)

    ' Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length \ 1024} KB")
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length \ 1024} KB")
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length \ 1024} KB")
End Sub

' Comparison example
Public Sub CompareFileSizes()
    Dim renderer As New ChromePdfRenderer()

    ' Method 1: External image reference
    Dim htmlExternal As String = "<img src='large-photo.jpg'>"
    Dim pdfExternal As PdfDocument = renderer.RenderHtmlAsPdf(htmlExternal, "C:\images\")

    ' Method 2: Base64 encoded image
    Dim imageBytes As Byte() = File.ReadAllBytes("C:\images\large-photo.jpg")
    Dim base64Image As String = Convert.ToBase64String(imageBytes)
    Dim htmlBase64 As String = $"<img src='data:image/jpeg;base64,{base64Image}'>"
    Dim pdfBase64 As PdfDocument = renderer.RenderHtmlAsPdf(htmlBase64)

    ' Compare sizes
    Console.WriteLine($"Original image: {imageBytes.Length \ 1024} KB")
    Console.WriteLine($"PDF with external image: {pdfExternal.BinaryData.Length \ 1024} KB")
    Console.WriteLine($"PDF with base64 image: {pdfBase64.BinaryData.Length \ 1024} KB")
End Sub

For optimal results:

Use base64 for small icons and logos (< 50KB)
Use external references for large images and photographs
Consider compression before encoding
Use appropriate image formats for content type

For advanced PDF optimization techniques, explore our PDF compression guide.

Frequently Asked Questions

What is the purpose of using Base URLs in IronPDF?

Base URLs in IronPDF are used to specify the location of CSS, JavaScript, and image assets during HTML to PDF conversion, ensuring these assets are properly loaded by providing a `BaseUrlOrPath` parameter.

How can I implement base URLs in a basic scenario using IronPDF?

You can implement base URLs by setting the `BaseUrlOrPath` parameter in IronPDF's HTML to PDF generation code. This enables smooth asset loading and ensures all CSS, JavaScript, and images are correctly referenced during the conversion process.

Why might my image assets not be loading correctly in my PDF?

If image assets are not loading correctly, ensure absolute paths are used, check file permissions, test with remote URLs, and enable logging for debugging. IronPDF also provides custom options like `BaseUrlOrPath` to accurately reference asset locations.

How do I set different base URLs for PDF headers and main content in IronPDF?

In IronPDF, you can configure different base URLs for headers, footers, and main content by using the `HtmlHeaderFooter` class to set distinct `BaseUrl` properties for each section.

What should I be aware of when using `CustomCssUrl` in IronPDF?

`CustomCssUrl` is used when rendering HTML strings to PDFs. It allows you to specify additional stylesheets for better PDF rendering and is ideal for print-specific styles, PDF layout optimization, and conditional formatting.

When should I use Base64 encoding for images in IronPDF?

Base64 encoding is useful for embedding images directly into HTML content to avoid external dependency issues, enhance compatibility across platforms, and increase reliability in production environments without accessing the file system.

How does Base64 encoding affect the size of my PDFs?

Base64 encoding increases HTML and subsequently PDF size due to data being represented in a larger format. Use it for smaller images, while larger assets should use external references to optimize PDF size.

What are the benefits of using Base64 encoding in IronPDF?

Base64 encoding benefits include creating self-contained HTML, ensuring cross-platform compatibility, reducing security risks by eliminating file system access, and preventing missing asset errors in live environments.

How do I handle relative asset paths in HTML files for PDF conversion in IronPDF?

Ensure your file structure supports the relative paths in your HTML file, and use `RenderHtmlFileAsPdf` from IronPDF to convert HTML files to PDFs while correctly loading CSS and JavaScript resources.

Why don't headers and footers in IronPDF inherit Base URLs from the main document?

Headers and footers in IronPDF do not inherit Base URLs from the main document to maintain styling independence, ensure consistent rendering, and allow flexible asset organization for optimal PDF creation.

Curtis Chau

Chat with engineering team now

Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Ready to Get Started?

Nuget Downloads 21,105,021|Version:2026.9just released

Free NuGet Download

Total downloads: 21,105,021

View Licenses

How to Use Base URLs in PDF Generation with C#

View on GitHub

Install with NuGet

Version: 2026.9

PM > Install-Package IronPdf

nuget.org/packages/IronPdf/

In Solution Explorer, right-click References, Manage NuGet Packages
Select Browse and search "IronPdf"
Select the package and install

Download DLL

Version: 2026.9

or download Windows Installer here.

Download and unzip IronPDF to a location such as ~/Libs within your Solution directory
In Visual Studio Solution Explorer, right click References. Select Browse, "IronPdf.dll"

Licenses from $999