Adding Dynamic Images to Your Merged PDFs
Static PDFs are fine for plain text, but many documents need personalized images — employee photos on ID badges, product images on invoices, company logos on letters, or student photos on certificates. Mergram’s image fields let you embed different images into each merged PDF based on your spreadsheet data.
Prerequisites
To use image fields in your merged PDFs, you need:
- A PDF template uploaded to Mergram
- A spreadsheet with a column containing image filenames (e.g.,
photo.jpg,logo.png) - Your image files in PNG or JPEG format, ready to upload
- A Mergram account
PNG and JPEG only
Mergram embeds images using the PDF standard, which supports PNG and JPEG natively. Other formats (WebP, BMP, TIFF, GIF, SVG) are not supported. Convert your images before uploading for reliable results.
How Image Fields Work
The image field workflow connects your spreadsheet data to a library of uploaded images:
- Upload images to a Media Album (team-scoped storage)
- Name your images with filenames that match your spreadsheet values
- Place an image field on the canvas tied to a spreadsheet column
- Merge — for each row, Mergram looks up the cell value, finds the matching image, and embeds it
This means the spreadsheet acts as the “lookup key” — each cell tells Mergram which image to use for that row.
Setting Up Media Albums
Media Albums organize your images into named collections. Each album belongs to your team and can be linked to templates.
Creating an Album
- Go to Assets → Media Albums
- Click Create Album and give it a descriptive name (e.g., “Employee Photos”, “Product Images”)
- Upload your images (PNG or JPEG, up to 10MB each)
Naming Convention Best Practices
Your image filenames must match the values in your spreadsheet. Here are recommended naming patterns:
| Pattern | Filename Example | Spreadsheet Value | Notes |
|---|---|---|---|
| By person name | alice-chen.jpg | alice-chen | Case-insensitive match |
| By ID | EMP001.png | EMP001 | Reliable, avoids name conflicts |
| By product code | SKU-12345.jpg | SKU-12345 | Good for product catalogs |
| By filename | photo.jpg | photo.jpg | Full filename with extension |
Stem fallback matching
Mergram matches cell values against image filenames using case-insensitive comparison with stem fallback. This means a cell value of ‘alice’ matches an uploaded file named ‘alice.jpg’, ‘alice.png’, or ‘alice.PNG’. You don’t need to include the file extension in your spreadsheet — but you can if you prefer.
Placing Image Fields on the Canvas
Step 1: Select the Image Column
In the editor sidebar, find the column that contains your image filenames (e.g., “Photo”, “Logo”, “ProductImage”).
Step 2: Set Render Type to Image
Drag the column onto the canvas. Change the render type from “Text” to “Image”. A bounding box appears that represents where the image will be placed.
Step 3: Resize and Position
Adjust the bounding box to control the image dimensions and placement:
- Width determines the image size — images scale to cover the bounding box width while maintaining aspect ratio
- Position on the canvas controls where the image appears on the page
- Margin adds padding inside the bounding box
- Opacity — adjust transparency in the field properties toolbar to overlay images on top of existing content
- Images are aligned to the top-left corner of the bounding box
Real-World Examples
Employee ID Badges
| Spreadsheet Column | Example Value | Purpose |
|---|---|---|
FirstName | Alice | Name on badge |
LastName | Chen | Name on badge |
Department | Engineering | Department label |
EmployeeID | EMP001 | ID number |
Photo | alice-chen | Image field — matches alice-chen.jpg in album |
Place the Photo field as an Image type at the top of the badge.
Product Invoices with Images
| Spreadsheet Column | Example Value | Purpose |
|---|---|---|
ClientName | Acme Corp | Invoice header |
Amount | $1,250.00 | Invoice total |
ProductCode | SKU-12345 | Product reference |
ProductImage | SKU-12345 | Image field — matches SKU-12345.jpg |
Place ProductImage as an Image type next to the product description.
Certificates with Signatures
Upload signature images (scanned signatures as transparent PNGs) to an album. Map a “Signature” column to place the correct signer’s signature on each certificate.
Best Practices for Image Fields
- Resize images before uploading — A 4000px photo displayed at 200px wastes storage and slows processing. Resize to roughly the display dimensions.
- Use consistent filenames — Decide on a naming convention and stick to it. Mixing patterns (some with extensions, some without) causes missed matches.
- Test with 5–10 rows first — Upload a few images, match them to sample rows, and preview before uploading your entire image library.
- Use PNG for transparency — Logos and signatures with transparent backgrounds should be PNG. JPEG does not support transparency.
- Keep file sizes reasonable — Aim for under 1MB per image. Large images slow down both preview and bulk merge processing.
Common Issues and Troubleshooting
Images not appearing in merged PDFs: Check that your Media Album is linked to the template (via the Media tab in the editor sidebar). Also verify that the spreadsheet values exactly match the uploaded filenames — extra spaces, different extensions, or case differences can cause mismatches.
Wrong image for a row: The matching is based on the cell value and filename. If two images have similar names (e.g., photo1.jpg and photo10.jpg), make sure the cell value is specific enough to match only the intended file.
Upload fails with large images: The per-file limit is 10MB. Resize your images to a reasonable resolution (300 DPI at print size is plenty) and re-upload.
Get Started
Create a Media Album, upload your images, and start placing image fields in the Mergram editor. Preview with real data to see your dynamic images rendered live before running the full merge.