How to Add Image to DOCX in C#

Ahmad Sohail

Updated: August 2, 2026

Download IronWord

• NuGet Download
• DLL Download

• ---

• Start Free Trial

Copy for LLMs

• Copy for LLMs

  Copy page as Markdown for LLMs
  # How to Add Image to DOCX in C&#35; IronWord provides the `ImageContent` class to insert images (.jpg, .png, .bmp, .tiff, .gif) into DOCX files with customizable properties like width, height, and text wrapping. Use IronWord to add images to Word documents for document automation and report generation. *as-heading:2(Quickstart: Add Image to DOCX in C#)* 1. Install IronWord via NuGet Package Manager 2. Create a new `WordDocument` instance 3. Load your image using `ImageContent` class 4. Add the image to the document using `AddImage()` 5. Save the document as DOCX ```csharp :title=Quickstart using IronWord; using IronWord.Models; // Create new document WordDocument doc = new WordDocument(); // Add image ImageContent image = new ImageContent("photo.jpg"); doc.AddImage(image); // Save document doc.SaveAs("document-with-image.docx"); ``` <h3>Try IronWord</h3> --- <div class="hsg-featured-snippet"> <h2>How to Add an Image to DOCX</h2> <ol> <li>Download the latest stable version of IronWord</li> <li>Initialize a new Word document</li> <li>Define an image object (.bmp, .jpg, .png, or other supported formats)</li> <li>Add the image to the document</li> <li>Save and export the document file</li> </ol> </div> ## How Do I Add an Image to DOCX? Reference an image using its file path. First, instantiate the `ImageContent` class with the file path as a string. Use the `image` variable throughout the file to modify properties like width and height. Add the image to the .docx file using the `AddImage()` function. Export and save the document locally. The example below adds an image to the document without any parent node. Supported file formats include .jpg, .png, .bmp, .tiff, and .gif. This flexibility lets you work with any common image format. [[t:(Insert an image and configure its width and height before adding it directly to the document. This approach lets you set dimensional properties prior to insertion.)]] ```csharp :path=/static-assets/word/content-code-examples/how-to/add-image-insert-image.cs ``` <div class="content-img-align-center"> <div class="center-image-wrapper"> <img src="/static-assets/word/how-to/add-image/add-image.webp" alt="Word document showing inserted nighttime city skyline image with Home tab ribbon displaying formatting options" class="img-responsive add-shadow" /> </div> </div> ### Which Image Formats Are Supported? Supported file formats: .jpg, .png, .bmp, .tiff, and .gif. Each format maintains its quality when inserted. JPEG works best for photographs. PNG supports transparency for logos and graphics. BMP provides uncompressed quality. TIFF suits high-quality print documents. GIF allows simple animations (only the first frame displays in static documents). ### Where Is the Image Placed in the Document? Images are added at the current cursor position by default, without any parent node. For precise positioning, insert images as child elements within paragraphs. This provides better control over text flow and integrates images with your document's structure. ### Why Use ImageContent Class? The `ImageContent` class manages image properties in a structured way. Modify dimensions, positioning, and formatting before insertion. This approach ensures consistency across your document generation process and applies standard formatting rules throughout your application. The class encapsulates all image-related properties, making code more maintainable and reducing formatting errors. ## How Do I Add Images via Stream? Local or static URL images are easy to add using the previous method. However, applications often work with images from databases, web services, or dynamically generated content. Use the `Stream` method to add images behind secure APIs requiring authentication. The example below shows an HTTP client sending authorization tokens to retrieve an authenticated image stream. The stream integrates directly into the document before export. This approach eliminates temporary file storage and improves security for sensitive image data. ```csharp :path=/static-assets/word/content-code-examples/how-to/add-image-insert-image-via-http-stream.cs ``` ### When Should I Use Stream Method? Use the `Stream` method when: - Images are behind secure APIs requiring authentication - Processing images dynamically from memory - Working with images stored as binary data in databases This method works well in enterprise applications where images are stored in document management systems, cloud storage, or generated by image processing services. ### What Are the Benefits of Stream Loading? Stream loading integrates images from authenticated endpoints without saving temporary files. This improves security and performance. Benefits include: - Reduced disk I/O operations - No sensitive image caching on disk - Real-time image processing workflows - Better memory management for large images - Flexible image source options ## How Can I Modify Image Properties? IronWord provides comprehensive methods to customize image properties. Adjust these properties before or after adding the image to the document. [[i:(`Width`, `Height`, and the `DistanceFrom*` properties default to points (1 inch = 72 points) when assigned directly, as shown below. To work in a different unit, use the corresponding `Get`/`Set` overload instead — for example, `image.SetWidth(5, MeasurementUnit.Centimeter)`.)]] <div class="content-table dotnet-core-pdf-table"> <table> <tbody> <tr class="tr-head"> <th class="tcol1">Settings</th> <th class="tcol2">Description</th> <th class="tcol3">Example</th> </tr> <tr> <td><code>Width</code></td> <td>Horizontal dimension of the image, in points (1 inch = 72 points)</td> <td><code>image.Width = 500;</code></td> </tr> <tr> <td><code>Height</code></td> <td>Vertical dimension of the image, in points (1 inch = 72 points)</td> <td><code>image.Height = 300;</code></td> </tr> <tr> <td><code>TextWrapBehavior</code></td> <td>Text wrapping behavior around the image. Its type is the <code>ITextWrapBehavior</code> interface; no public implementing class or factory is currently documented for constructing a value, so no working example is shown here pending product-team confirmation.</td> <td>-</td> </tr> <tr> <td><code>DistanceFromLeft</code></td> <td>Spacing measurement from left edge, in points</td> <td><code>image.DistanceFromLeft = 10;</code></td> </tr> <tr> <td><code>DistanceFromRight</code></td> <td>Spacing measurement from right edge, in points</td> <td><code>image.DistanceFromRight = 10;</code></td> </tr> <tr> <td><code>DistanceFromTop</code></td> <td>Spacing measurement from top edge, in points</td> <td><code>image.DistanceFromTop = 15;</code></td> </tr> <tr> <td><code>DistanceFromBottom</code></td> <td>Spacing measurement from bottom edge, in points</td> <td><code>image.DistanceFromBottom = 15;</code></td> </tr> <tr> <td><code>Position</code></td> <td>Spatial placement information (X and Y coordinates)</td> <td><code>var pos = new ElementPosition(); pos.SetXPosition(50, MeasurementUnit.Point); pos.SetYPosition(100, MeasurementUnit.Point); image.Position = pos;</code></td> </tr> </tbody> </table> </div> ### How Do I Customize Width & Height? Implement custom width and height by altering the aspect ratio. Control how images appear in documents whether maintaining proportions or fitting into specific layout constraints. ```csharp :path=/static-assets/word/content-code-examples/how-to/add-image-custom-size.cs ``` <div class="content-img-align-center"> <div class="center-image-wrapper"> <img src="/static-assets/word/how-to/add-image/add-image-custom-size.webp" alt="Word document showing laptop image with 'Tagged Image File F' overlay text demonstrating image property display" class="img-responsive add-shadow" /> </div> </div> ### What Happens to Aspect Ratio? Custom width and height values override the original aspect ratio. Stretch or compress images to fit layout requirements like headers, sidebars, or fixed-size containers. Extreme distortion can look unprofessional. To maintain aspect ratio while resizing, calculate proportional dimensions based on your target size. ### Which Properties Should I Set First? Set properties in this order: 1. Dimensions (width/height) - foundation of image layout 2. Positioning (DistanceFrom properties) - control spacing and margins 3. Advanced properties (position, text wrap) - fine-tuning This approach ensures each property builds logically on previous ones. Some properties interact - text wrapping affects how distance properties work.

• ---

• Open in ChatGPT

  Ask ChatGPT about this page
• Open in Gemini

  Ask Gemini about this page
• Open in Grok

  Ask Grok about this page
• Open in Perplexity

  Ask Perplexity about this page

Share

• Share on Facebook
• Share on X (Twitter)
• Share on LinkedIn

• ---

• Email article

IronWord provides the ImageContent class to insert images (.jpg, .png, .bmp, .tiff, .gif) into DOCX files with customizable properties like width, height, and text wrapping. Use IronWord to add images to Word documents for document automation and report generation.

1. Install IronWord via NuGet Package Manager
2. Create a new WordDocument instance
3. Load your image using ImageContent class
4. Add the image to the document using AddImage()
5. Save the document as DOCX

Try IronWord

How Do I Add an Image to DOCX?

Reference an image using its file path. First, instantiate the ImageContent class with the file path as a string. Use the image variable throughout the file to modify properties like width and height. Add the image to the .docx file using the AddImage() function. Export and save the document locally.

The example below adds an image to the document without any parent node. Supported file formats include .jpg, .png, .bmp, .tiff, and .gif. This flexibility lets you work with any common image format.

using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.jpg");

// modifying image properties
image.Width = 200;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("inserted-image.docx");

using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.jpg");

// modifying image properties
image.Width = 200;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("inserted-image.docx");

Imports IronWord
Imports IronWord.Models
Imports IronWord.Models.Enums

' Initializing docx file
Dim doc As New IronWord.WordDocument()

' Instantiating image file
Dim image As New IronWord.Models.ImageContent("sample-image.jpg")

' Modifying image properties
image.Width = 200
image.Height = 200

' AddImage function saving the image
doc.AddImage(image)

' Save and export the file
doc.SaveAs("inserted-image.docx")

Imports IronWord
Imports IronWord.Models
Imports IronWord.Models.Enums

' Initializing docx file
Dim doc As New IronWord.WordDocument()

' Instantiating image file
Dim image As New IronWord.Models.ImageContent("sample-image.jpg")

' Modifying image properties
image.Width = 200
image.Height = 200

' AddImage function saving the image
doc.AddImage(image)

' Save and export the file
doc.SaveAs("inserted-image.docx")

Which Image Formats Are Supported?

Supported file formats: .jpg, .png, .bmp, .tiff, and .gif. Each format maintains its quality when inserted. JPEG works best for photographs. PNG supports transparency for logos and graphics. BMP provides uncompressed quality. TIFF suits high-quality print documents. GIF allows simple animations (only the first frame displays in static documents).

Where Is the Image Placed in the Document?

Images are added at the current cursor position by default, without any parent node. For precise positioning, insert images as child elements within paragraphs. This provides better control over text flow and integrates images with your document's structure.

Why Use ImageContent Class?

The ImageContent class manages image properties in a structured way. Modify dimensions, positioning, and formatting before insertion. This approach ensures consistency across your document generation process and applies standard formatting rules throughout your application. The class encapsulates all image-related properties, making code more maintainable and reducing formatting errors.

How Do I Add Images via Stream?

Local or static URL images are easy to add using the previous method. However, applications often work with images from databases, web services, or dynamically generated content. Use the Stream method to add images behind secure APIs requiring authentication.

The example below shows an HTTP client sending authorization tokens to retrieve an authenticated image stream. The stream integrates directly into the document before export. This approach eliminates temporary file storage and improves security for sensitive image data.

using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

using (HttpClient client = new HttpClient())
{
    // Add authentication headers
    client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY_HERE");
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0");

    // Get image from authenticated endpoint
    Stream authenticatedStream = await client.GetStreamAsync("https://api.example.com/secure/image.png");
    doc.AddImage(authenticatedStream);
}

// Export docx
doc.SaveAs("added-image-via-http-stream.docx");

using IronWord;
using IronWord.Models;
using IronWord.Models.Enums;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

using (HttpClient client = new HttpClient())
{
    // Add authentication headers
    client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY_HERE");
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0");

    // Get image from authenticated endpoint
    Stream authenticatedStream = await client.GetStreamAsync("https://api.example.com/secure/image.png");
    doc.AddImage(authenticatedStream);
}

// Export docx
doc.SaveAs("added-image-via-http-stream.docx");

Imports IronWord
Imports IronWord.Models
Imports IronWord.Models.Enums
Imports System.IO
Imports System.Net.Http
Imports System.Threading.Tasks

' initializing docx file
Dim doc As New IronWord.WordDocument()

Using client As New HttpClient()
    ' Add authentication headers
    client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY_HERE")
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0")

    ' Get image from authenticated endpoint
    Dim authenticatedStream As Stream = Await client.GetStreamAsync("https://api.example.com/secure/image.png")
    doc.AddImage(authenticatedStream)
End Using

' Export docx
doc.SaveAs("added-image-via-http-stream.docx")

Imports IronWord
Imports IronWord.Models
Imports IronWord.Models.Enums
Imports System.IO
Imports System.Net.Http
Imports System.Threading.Tasks

' initializing docx file
Dim doc As New IronWord.WordDocument()

Using client As New HttpClient()
    ' Add authentication headers
    client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY_HERE")
    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0")

    ' Get image from authenticated endpoint
    Dim authenticatedStream As Stream = Await client.GetStreamAsync("https://api.example.com/secure/image.png")
    doc.AddImage(authenticatedStream)
End Using

' Export docx
doc.SaveAs("added-image-via-http-stream.docx")

When Should I Use Stream Method?

Use the Stream method when:

• Images are behind secure APIs requiring authentication
• Processing images dynamically from memory
• Working with images stored as binary data in databases

This method works well in enterprise applications where images are stored in document management systems, cloud storage, or generated by image processing services.

What Are the Benefits of Stream Loading?

Stream loading integrates images from authenticated endpoints without saving temporary files. This improves security and performance. Benefits include:

• Reduced disk I/O operations
• No sensitive image caching on disk
• Real-time image processing workflows
• Better memory management for large images
• Flexible image source options

How Can I Modify Image Properties?

IronWord provides comprehensive methods to customize image properties. Adjust these properties before or after adding the image to the document.

How Do I Customize Width & Height?

Implement custom width and height by altering the aspect ratio. Control how images appear in documents whether maintaining proportions or fitting into specific layout constraints.

using IronWord;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.tiff");

// modifying the aspect ratio by introducing custom width
image.Width = 800;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("custom-size-image.docx");

using IronWord;

// initializing docx file
WordDocument doc = new IronWord.WordDocument();

// instantiating image file
IronWord.Models.ImageContent image = new IronWord.Models.ImageContent("sample-image.tiff");

// modifying the aspect ratio by introducing custom width
image.Width = 800;
image.Height = 200;

// AddImage function saving the image
doc.AddImage(image);

// Save and export the file
doc.SaveAs("custom-size-image.docx");

Imports IronWord

' initializing docx file
Dim doc As New IronWord.WordDocument()

' instantiating image file
Dim image As New IronWord.Models.ImageContent("sample-image.tiff")

' modifying the aspect ratio by introducing custom width
image.Width = 800
image.Height = 200

' AddImage function saving the image
doc.AddImage(image)

' Save and export the file
doc.SaveAs("custom-size-image.docx")

Imports IronWord

' initializing docx file
Dim doc As New IronWord.WordDocument()

' instantiating image file
Dim image As New IronWord.Models.ImageContent("sample-image.tiff")

' modifying the aspect ratio by introducing custom width
image.Width = 800
image.Height = 200

' AddImage function saving the image
doc.AddImage(image)

' Save and export the file
doc.SaveAs("custom-size-image.docx")

What Happens to Aspect Ratio?

Custom width and height values override the original aspect ratio. Stretch or compress images to fit layout requirements like headers, sidebars, or fixed-size containers. Extreme distortion can look unprofessional. To maintain aspect ratio while resizing, calculate proportional dimensions based on your target size.

Which Properties Should I Set First?

Set properties in this order:

1. Dimensions (width/height) - foundation of image layout
2. Positioning (DistanceFrom properties) - control spacing and margins
3. Advanced properties (position, text wrap) - fine-tuning

This approach ensures each property builds logically on previous ones. Some properties interact - text wrapping affects how distance properties work.

Ahmad Sohail

Chat with engineering team now

Full Stack Developer

Ahmad is a full-stack developer with a strong foundation in C#, Python, and web technologies. He has a deep interest in building scalable software solutions and enjoys exploring how design and functionality meet in real-world applications.

...

Read More