# Images > Merge images into templates: named image placeholders, Base64 data, files and SVG, RemoveEmptyImages, the ImageMerged event and image merge fields. - **Product:** TX Text Control .NET Server - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET Server > Mail Merge and Reporting > Images - **2584 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms-full.txt --- Logos, product photos and signatures in merged documents usually come from the data, not from the template. The template contains a placeholder image with a name; during the merge, `MailMerge` replaces it with the image data of the same name and keeps its size and position. You create such placeholders, merge image data from JSON and files, handle placeholders without data and change the merged images in code. Inserting and positioning images in general is described in [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/images/llms-full.txt) in Document Processing. The examples extend the invoice data of [Simple Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/mail-merge/simple/llms-full.txt) with a logo. ### How Image Placeholders Work An image placeholder is an ordinary image in the template whose name matches a field of the data. During the merge, `MailMerge` replaces the placeholder with the image from the data: - **Size.** The merged image is scaled to the width of the placeholder. - **Layout.** The position and the text flow of the placeholder, such as an image anchored at the right of a paragraph, are kept. - **Data.** The value of the field can be image data as a byte array or a `System.Drawing.Image`, a Base64 string, a hexadecimal string that starts with `X'`, the name of an image file or SVG markup as plain XML text. - **Missing data.** A placeholder without data stays in the document, unless [RemoveEmptyImages](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/removeemptyimages-property/llms-full.txt) is `true`. Images in merge blocks are merged for each record, so a product table can show a photo in every row. The names of placeholders follow the same rules as the names of merge fields, including dot notation for related data. In a merge block, the name starts at the table of the block and can pass through several related tables: in the sample database of TX Text Control Words, a placeholder in the order line block `Sales_SalesOrderDetail` named `Production_Product.Production_ProductProductPhoto.Production_ProductPhoto.ThumbNailPhoto` receives the thumbnail photo of the product of each order line. [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/fields/#prefixes-in-field-names) describes the tables of this example. ![Placeholder image in TX Text Control Words with its context menu open at Select Object Data Source, which lists the tables of the sample database](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/object-data-source-menu.215303a6.webp) ![Field dialog of TX Text Control Words with the related tables Production_ProductProductPhoto and Production_ProductPhoto expanded, listing the columns ThumbNailPhoto and ThumbnailPhotoFileName](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/product-photo-field-tree.c1adc927.webp) JSON data carries images as Base64 strings, which makes the data self-contained. Add a `Logo` property with the Base64 data of a PNG image to the invoice in *data.json*: ```json [ { "InvoiceNumber": "INV-2025-001", "Logo": "iVBORw0KGgoAAAANSUhEUgAA...", "Customer": { "CustomerName": "Acme Corporation" } } ] ``` The value is shortened here; use the complete Base64 string of your image. ### Create a Template With an Image Placeholder In code, a placeholder is an image with a [Name](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/framebase/name-property/llms-full.txt). The following program inserts a placeholder image named `Logo` and saves the template: ```csharp using TXTextControl; using (ServerTextControl tx = new ServerTextControl()) { tx.Create(); byte[] placeholderData = File.ReadAllBytes("Documents/placeholder.png"); // The stream must be publicly visible for the Image class using (MemoryStream stream = new MemoryStream(placeholderData, 0, placeholderData.Length, false, true)) { Image placeholder = new Image(stream); tx.Images.Add(placeholder, -1); // The name connects the placeholder with the data placeholder.Name = "Logo"; } tx.Selection.Text = "\r\nInvoice "; tx.Save("image-template.tx", StreamType.InternalUnicodeFormat); } ``` The code works as follows: - The [Image constructor](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/image/constructor/llms-full.txt) with a `MemoryStream` reads the image data, so the template contains the image itself and not a reference to a file. - [ImageCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/imagecollection/add-method/llms-full.txt) with `-1` inserts the image inline at the input position. - The template is saved in the TX Text Control format, which the samples of Text Control use for image placeholders. The size you give the placeholder is the width of every image merged into it. [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/images/#position-an-image-on-the-page) in Document Processing shows how to anchor the image or place it at a fixed position. In the Document Editor, a placeholder is created the same way from JavaScript: insert an image and give it a name with `setName`, as [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/images/llms-full.txt) in the Document Editor section describes. ### Merge Images From Data The following program merges the invoice data with the logo into the template, removes placeholders without data and sets the alternative text of the merged logo: ```csharp using TXTextControl; using TXTextControl.DocumentServer; using (ServerTextControl tx = new ServerTextControl()) { tx.Create(); tx.Load("image-template.tx", StreamType.InternalUnicodeFormat); using (MailMerge mailMerge = new MailMerge { TextComponent = tx, RemoveEmptyImages = true }) { mailMerge.ImageMerged += (sender, e) => { // Alternative text for accessible PDF documents if (e.Merged && e.Name == "Logo") { e.DescriptiveText = "Company logo"; } }; mailMerge.MergeJsonData(File.ReadAllText("data.json")); } tx.Save("invoice-with-logo.pdf", StreamType.AdobePDF); } ``` The code works as follows: - `RemoveEmptyImages` removes a placeholder when the data has no image for it. By default, the placeholder image stays in the document. - The [ImageMerged](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/imagemerged-event/llms-full.txt) event occurs when an image has been merged. Its arguments contain the [Name](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-imagemergedeventargs/name-property/llms-full.txt) of the image, whether it was [Merged](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-imagemergedeventargs/merged-property/llms-full.txt) and the [MergeBlockName](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-imagemergedeventargs/mergeblockname-property/llms-full.txt) of an image in a merge block. - [DescriptiveText](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-imagemergedeventargs/descriptivetext-property/llms-full.txt) replaces the descriptive text of the image, which accessible PDF documents use as alternative text. [Image](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge-imagemergedeventargs/image-property/llms-full.txt) gives access to the merged image: a byte array with the Core engine, a `System.Drawing.Image` with the Classic engine. The online demo [Merging images](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/images) merges a Base64 logo into a template in the same way. ### Merge Images From Files When the data contains file names instead of image data, such as `"Logo": "logo.png"`, `MailMerge` looks for the files in the folder that [MailMerge.SearchPath](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/searchpath-property/llms-full.txt) sets. Without a search path, it uses the root directory: ```csharp using (MailMerge mailMerge = new MailMerge { TextComponent = tx, // Image files are searched in this folder SearchPath = Path.Combine(AppContext.BaseDirectory, "Images") }) { mailMerge.MergeJsonData(File.ReadAllText("data.json")); } ``` ### Merge SVG Images Placeholders can also receive SVG images. The SVG markup is the value of the field as plain XML text, not Base64 encoded. In a PDF, SVG images are stored as vector graphics. The blog article [Service Pack 3: MailMerge Supports SVG Images](https://www.textcontrol.com/blog/2024/04/29/service-pack-3-mailmerge-supports-svg-images/) shows an example. ### Image Merge Fields Before named placeholders were introduced, images were merged into merge fields whose name starts with `image:`, such as `image:Logo`. `MailMerge` still merges such fields as images, and the [ImageFieldMerged](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/imagefieldmerged-event/llms-full.txt) event gives access to the merged image as a `TXTextControl.Image` that your code can replace. Named image placeholders, which came later, also keep the size and layout of the placeholder in the template. ### Next Steps - [Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/llms-full.txt): merge values into barcode placeholders the same way. - [Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/blocks/llms-full.txt): repeat images for each record. - [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-processing/images/llms-full.txt) in Document Processing: insert and position images in code. - [Data Sources](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/data-sources/llms-full.txt): the data that carries the images. --- ## Nearby - **Previous:** [Nested Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/nested-blocks/llms-full.txt) - **Next:** [Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/llms-full.txt)