IronPDF How-Tos Base URLs & Asset Encoding How to Use Base URLs & Asset Encoding Chaknith Bin Updated:June 22, 2025 IronPDF is a useful tool for generating PDF documents in .NET projects. A common use of this library is “HTML to PDF” rendering - where HTML is used as the design language for rendering a PDF document. A logical question is: how can we use CSS stylesheets and Image files in our HTML to PDF Conversion? How to Use HTML with CSS and Images Download IronPDF for HTML to CSS to Image Support Specify BaseUrlOrPath parameter to use external images in HTML Configure the correct src in MVC to show both in web and output PDF Specify BaseUrl property to work with custom header and footer Check the output PDF Rendering a PDF from HTML String with Image and CSS Assets When working with HTML String to PDF conversion, it's important to set a BaseUrlOrPath parameter for assets such as CSS, JavaScript files, and images. The BaseUrlOrPath specifies the base URL from which all assets will be loaded relative to. This can be a web URL starting with 'http' to load remote assets or a local file path to access assets on your disk. Setting the BaseUrlOrPath correctly ensures that the assets are loaded correctly during the conversion process. :path=/static-assets/pdf/content-code-examples/how-to/base-urls-baseurl.cs 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"); Imports IronPdf ' Instantiate ChromePdfRenderer Private renderer As New ChromePdfRenderer() Private baseUrl As String = "C:\site\assets\" Private html As String = "<img src='icons/iron.png'>" ' Render HTML to PDF Private pdf As PdfDocument = renderer.RenderHtmlAsPdf(html, baseUrl) ' Export PDF pdf.SaveAs("html-with-assets.pdf") $vbLabelText $csharpLabel MVC application In an MVC application, specifying the file path of an image can be challenging. To ensure that the image can be found by IronPDF and displayed correctly on the website, the baseUrl of IronPDF and src="" attribute on HTML string need to be configured correctly. With the file hierarchy shown below set baseUrlOrPath to @"wwwroot/image" src attribute to "../image/Sample.jpg" wwwroot └── image ├── Sample.jpg └── Sample.png For example: :path=/static-assets/pdf/content-code-examples/how-to/base-mvc.cs // 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") $vbLabelText $csharpLabel <img src="../image/Sample.jpg"/> <img src="../image/Sample.png"/> <img src="../image/Sample.jpg"/> <img src="../image/Sample.png"/> HTML Warning File Path Formats That Do Not Work The following formats work well when viewing on Chrome browser, but point to the wrong folder directory when used in an MVC app. These formats still 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 On the other hand, these formats work well with MVC app, but when it comes to file path, these formats do not work well in IronPDF: <img src="/image/footer.png"/> <img src="~/image/footer.png"/> <img src="/image/footer.png"/> <img src="~/image/footer.png"/> HTML HTML Headers and Footers with Images and Assets When we render HTML headers and footers to a new or existing PDF, they are treated as standalone HTML documents and do not inherit the BaseURL from the PDF itself. We should set a BaseURL from which assets may be loaded: :path=/static-assets/pdf/content-code-examples/how-to/base-header-footer.cs using IronPdf; using System; // Instantiate ChromePdfRenderer ChromePdfRenderer renderer = new ChromePdfRenderer(); // Add header renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter() { MaxHeight = 20, HtmlFragment = "<img src='logo.png'>", BaseUrl = new Uri(@"C:\assets\images\").AbsoluteUri }; Imports IronPdf Imports System ' Instantiate ChromePdfRenderer Private renderer As New ChromePdfRenderer() ' Add header renderer.RenderingOptions.HtmlHeader = New HtmlHeaderFooter() With { .MaxHeight = 20, .HtmlFragment = "<img src='logo.png'>", .BaseUrl = (New Uri("C:\assets\images\")).AbsoluteUri } $vbLabelText $csharpLabel HTML File to PDF with CSS, JS and Image Assets When rendering an HTML file to PDF, all assets will be assumed local to that file. :path=/static-assets/pdf/content-code-examples/how-to/base-html-file.cs 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") $vbLabelText $csharpLabel In the above example, all JS, CSS and image files will be loaded from the C:\Assets folder on the disk - the same directory that the HTML file is located. For convenience, you may use CustomCssUrl in ChromePdfRenderOptions for Additional Stylesheets to specify an additional stylesheet that is only used for .NET PDF rendering if you so desire. For example: :path=/static-assets/pdf/content-code-examples/how-to/base-html-file-baseurl.cs 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") $vbLabelText $csharpLabel Please noteThe ChromePdfRenderOptions.CustomCssUrl property is currently only functional when rendering from an HTML string to a PDF document using the RenderHtmlAsPdf method. Image Asset Encoding Image assets can be encoded directly into the HTML file or string, which can help avoid some of the frustrating issues of images not being found. To do this we can utilize the use of base64: First obtain the binary data of the image either by reading the image file or receiving it through a network request. Use the Convert.ToBase64String method in Microsoft .NET to convert the binary data to base64. Construct the image tag in HTML using "data:image/svg+xml;base64," before the base64 data. You may have noticed that the image type is being specified before the base64 data. Visit the MDN Web Docs on Image Types and Formats for more information on image format types. :path=/static-assets/pdf/content-code-examples/how-to/add-images-to-pdfs-base64-image.cs 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") $vbLabelText $csharpLabel Frequently Asked Questions What is the importance of using base URLs in HTML to PDF conversion? Base URLs are crucial in HTML to PDF conversion as they ensure that all related assets like CSS stylesheets, JavaScript files, and images are correctly loaded. In IronPDF, the BaseUrlOrPath parameter can be set to a web URL or a local file path to facilitate this process. How can you handle asset loading in an MVC application for PDF generation? In an MVC application using IronPDF, you can handle asset loading by configuring the BaseUrlOrPath parameter to point to the directory containing your assets. This way, your HTML will correctly reference CSS and image paths relative to this base path. What is asset encoding and why is it used in PDF generation? Asset encoding involves converting image data into a base64 string and embedding it within HTML. This technique, used with IronPDF, ensures that images are not missing during the PDF rendering process, especially when assets are not directly accessible from a URL or file path. How can you include additional stylesheets during PDF rendering in .NET? You can include additional stylesheets during PDF rendering in .NET using IronPDF's ChromePdfRenderOptions. By setting the CustomCssUrl property, you can specify external stylesheets to be used in the rendering process. What are some common troubleshooting steps for missing images in PDFs? Common troubleshooting steps for missing images in PDFs include verifying the correctness of the BaseUrlOrPath and the src attributes in your HTML. Ensuring these paths are accurate when using IronPDF will resolve most issues related to missing images. How can HTML headers and footers be rendered with images in PDFs? HTML headers and footers can be rendered with images in PDFs by setting a separate BaseURL for each. Using IronPDF, headers and footers are treated as standalone HTML documents, so it's important to ensure their base paths are correctly set for asset loading. Can you convert local HTML files with assets to PDF? Yes, you can convert local HTML files with assets to PDF using IronPDF. By ensuring that the BaseUrlOrPath is set to the HTML file's directory, IronPDF will correctly load all associated assets like CSS and images. Chaknith Bin Chat with engineering team now Software Engineer Chaknith works on IronXL and IronBarcode. He has deep expertise in C# and .NET, helping improve the software and support customers. His insights from user interactions contribute to better products, documentation, and overall experience. Ready to Get Started? Free NuGet Download Total downloads: 15,160,964 View Licenses