DEV Community

IronSoftware
IronSoftware

Posted on • Edited on

How to Add Images to PDF in C#

#csharp #dotnet #pdf #tutorial

PDFs often need images—logos in headers, signatures in contracts, charts in reports. Adding images programmatically means embedding them directly into the document so they display reliably everywhere, without external dependencies.

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();
var html = "<img src='logo.png' /><h1>Company Report</h1>";
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("report-with-image.pdf");
Enter fullscreen mode Exit fullscreen mode

IronPDF embeds images directly from HTML, making PDF generation feel like web development.

How Do I Add Images Using HTML?

The simplest approach: use standard HTML image tags.

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

var html = @"
<html>
<body>
    <img src='https://example.com/logo.png' style='width:200px;' />
    <h1>Annual Report 2024</h1>
    <p>Content goes here...</p>
</body>
</html>";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("report.pdf");
Enter fullscreen mode Exit fullscreen mode

IronPDF fetches the image from the URL during rendering. The image becomes embedded in the PDF—no external reference remains.

How Do I Embed Images with Base64?

Base64 encoding embeds the image data directly in the HTML. No network requests needed during rendering.

using IronPdf;
// Install via NuGet: Install-Package IronPdf

// Convert image to Base64
byte[] imageBytes = File.ReadAllBytes("logo.png");
string base64 = Convert.ToBase64String(imageBytes);
string dataUri = $"data:image/png;base64,{base64}";

var html = $@"
<html>
<body>
    <img src='{dataUri}' style='width:150px;' />
    <h1>Self-Contained Document</h1>
</body>
</html>";

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("self-contained.pdf");
Enter fullscreen mode Exit fullscreen mode

Base64 is ideal for:

  • Offline PDF generation
  • Consistent rendering without network dependencies
  • Embedding small logos and icons

How Do I Add Images to Existing PDFs?

Use the ImageStamper to place images on existing PDF pages:

using IronPdf;
using IronPdf.Stamps;
// Install via NuGet: Install-Package IronPdf

var pdf = PdfDocument.FromFile("document.pdf");

var stamp = new ImageStamper("signature.png")
{
    HorizontalAlignment = HorizontalAlignment.Right,
    VerticalAlignment = VerticalAlignment.Bottom,
    HorizontalOffset = new Length(20, MeasurementUnit.Pixels),
    VerticalOffset = new Length(20, MeasurementUnit.Pixels)
};

pdf.ApplyStamp(stamp);
pdf.SaveAs("signed-document.pdf");
Enter fullscreen mode Exit fullscreen mode

The stamper overlays images without modifying the original content.

How Do I Position Images Precisely?

Control exact placement with CSS or stamper properties:

using IronPdf;
using IronPdf.Stamps;
// Install via NuGet: Install-Package IronPdf

var pdf = PdfDocument.FromFile("report.pdf");

// Top-left logo
var logo = new ImageStamper("logo.png")
{
    HorizontalAlignment = HorizontalAlignment.Left,
    VerticalAlignment = VerticalAlignment.Top,
    HorizontalOffset = new Length(50),
    VerticalOffset = new Length(30)
};

// Bottom-right signature
var signature = new ImageStamper("signature.png")
{
    HorizontalAlignment = HorizontalAlignment.Right,
    VerticalAlignment = VerticalAlignment.Bottom,
    HorizontalOffset = new Length(-50),
    VerticalOffset = new Length(-50)
};

pdf.ApplyStamp(logo);
pdf.ApplyStamp(signature);
pdf.SaveAs("branded.pdf");
Enter fullscreen mode Exit fullscreen mode

For HTML-based positioning, use standard CSS:

var html = @"
<div style='position: absolute; top: 20px; right: 20px;'>
    <img src='watermark.png' style='opacity: 0.3; width: 100px;' />
</div>
<h1>Document Title</h1>";
Enter fullscreen mode Exit fullscreen mode

How Do I Resize Images?

Control dimensions with CSS or stamper scaling:

using IronPdf;
using IronPdf.Stamps;
// Install via NuGet: Install-Package IronPdf

var pdf = PdfDocument.FromFile("document.pdf");

var stamp = new ImageStamper("large-logo.png")
{
    // Scale to 50% of original size
    Scale = 50,
    HorizontalAlignment = HorizontalAlignment.Center,
    VerticalAlignment = VerticalAlignment.Top
};

pdf.ApplyStamp(stamp);
pdf.SaveAs("scaled-logo.pdf");
Enter fullscreen mode Exit fullscreen mode

In HTML, use width/height attributes or CSS:

// Fixed dimensions
var html1 = "<img src='photo.jpg' width='300' height='200' />";

// Percentage of container
var html2 = "<img src='photo.jpg' style='width: 50%;' />";

// Max dimensions (preserves aspect ratio)
var html3 = "<img src='photo.jpg' style='max-width: 400px; height: auto;' />";
Enter fullscreen mode Exit fullscreen mode

Which Image Formats Are Supported?

IronPDF supports common web image formats:

Format Best For
PNG Logos, graphics with transparency
JPEG Photos, complex images
GIF Simple animations, icons
SVG Scalable vector graphics
WebP Modern web images
BMP Uncompressed bitmaps 
using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

var html = @"
<img src='logo.svg' />      <!-- Scales perfectly -->
<img src='photo.jpg' />     <!-- Best for photos -->
<img src='icon.png' />      <!-- Supports transparency -->
";

var pdf = renderer.RenderHtmlAsPdf(html);
Enter fullscreen mode Exit fullscreen mode

SVG is ideal for logos—it scales without pixelation at any PDF zoom level.

How Do I Add Background Images?

CSS background images work just like on the web:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

var html = @"
<html>
<head>
    <style>
        body {
            background-image: url('watermark.png');
            background-repeat: no-repeat;
            background-position: center;
            background-size: 50%;
            background-attachment: fixed;
        }
        .content {
            padding: 50px;
        }
    </style>
</head>
<body>
    <div class='content'>
        <h1>Confidential Report</h1>
        <p>Document content here...</p>
    </div>
</body>
</html>";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("watermarked.pdf");
Enter fullscreen mode Exit fullscreen mode

For watermarks across all pages, the background-attachment: fixed property helps.

How Do I Handle Local Image Files?

When working with local files, set the base URL:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

// Set base path for relative image URLs
renderer.RenderingOptions.BaseUrl = new Uri("C:/Projects/Assets/");

var html = @"
<img src='images/logo.png' />
<img src='images/banner.jpg' />
";

var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("local-images.pdf");
Enter fullscreen mode Exit fullscreen mode

Alternatively, use absolute paths:

var html = @"<img src='file:///C:/Projects/Assets/logo.png' />";
Enter fullscreen mode Exit fullscreen mode

How Do I Add Images to Headers and Footers?

Place logos in page headers or footers:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

var renderer = new ChromePdfRenderer();

// Header with logo
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter
{
    HtmlFragment = @"
        <div style='display: flex; justify-content: space-between; align-items: center; padding: 10px;'>
            <img src='logo.png' style='height: 30px;' />
            <span>Company Name</span>
        </div>",
    DrawDividerLine = true
};

// Footer with page numbers
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter
{
    HtmlFragment = "<div style='text-align: center;'>Page {page} of {total-pages}</div>"
};

var pdf = renderer.RenderHtmlAsPdf("<h1>Report</h1><p>Content...</p>");
pdf.SaveAs("branded-report.pdf");
Enter fullscreen mode Exit fullscreen mode

Header images appear on every page automatically.

How Do I Stamp Images on Specific Pages?

Apply images to selected pages only:

using IronPdf;
using IronPdf.Stamps;
// Install via NuGet: Install-Package IronPdf

var pdf = PdfDocument.FromFile("multipage.pdf");

var stamp = new ImageStamper("approved.png")
{
    HorizontalAlignment = HorizontalAlignment.Center,
    VerticalAlignment = VerticalAlignment.Center,
    Opacity = 50  // Semi-transparent
};

// Apply only to first page
pdf.ApplyStamp(stamp, 0);

// Or apply to specific pages
pdf.ApplyStamp(stamp, new[] { 0, 2, 4 });

pdf.SaveAs("stamped.pdf");
Enter fullscreen mode Exit fullscreen mode

Page indices are zero-based.

How Do I Create Image-Based PDFs?

Convert images directly to PDF pages:

using IronPdf;
// Install via NuGet: Install-Package IronPdf

// Single image to PDF
var pdf = ImageToPdfConverter.ImageToPdf("scan.jpg");
pdf.SaveAs("scanned-document.pdf");

// Multiple images to multi-page PDF
var images = new[] { "page1.png", "page2.png", "page3.png" };
var multiPagePdf = ImageToPdfConverter.ImageToPdf(images);
multiPagePdf.SaveAs("multi-page-scan.pdf");
Enter fullscreen mode Exit fullscreen mode

Each image becomes a full page in the PDF.

Quick Reference

Task Approach
HTML image <img src='path.png' />
Base64 embed <img src='data:image/png;base64,...' />
Stamp existing PDF pdf.ApplyStamp(new ImageStamper("img.png"))
Header logo HtmlHeader.HtmlFragment
Image to PDF ImageToPdfConverter.ImageToPdf()
Position HorizontalAlignment, VerticalAlignment
Scale Scale property or CSS width/height

Images in PDFs should be embedded, not linked. IronPDF handles this automatically—whether from URLs, local files, or Base64 data.

For more image handling options, see the IronPDF image documentation.

Written by Jacob Mellor, CTO at Iron Software. Jacob created IronPDF and leads a team of 50+ engineers building .NET document processing libraries.

Top comments (0)