Image Fields — Mergram

How image fields work

Image fields let you dynamically insert images into your merged PDFs based on spreadsheet data. You upload images to a Media Album, then reference them by filename in your spreadsheet. When merging, Mergram matches spreadsheet values to album filenames and renders the corresponding images onto the PDF.

Supported image formats: PNG and JPEG.

Before you begin

Prepare your images before starting. Ensure all images are PNG or JPEG format, named clearly to match your spreadsheet data. For example, if your spreadsheet has employee IDs like EMP001, name the corresponding photo EMP001.png.

Prerequisites

A set of PNG or JPEG images to embed in your PDFs
A spreadsheet with a column containing image filenames (e.g., photo1, headshot.jpg, EMP001.png)
A Media Album to store and organize your images

Using Image Fields

Upload images to a Media Album Go to Assets → Media Albums and create an album (or use an existing one). Upload PNG or JPEG images. Each image’s filename (without extension) becomes its lookup key.
Prepare your spreadsheet Add a column with image filenames (with or without extension). For example, if your album contains photo1.png, your spreadsheet cell can be photo1 or photo1.png.

Organize your spreadsheet

Keep image filenames in a dedicated column. Avoid combining filenames with other data in the same cell. Use consistent naming — if your images are named EMP001.png, EMP002.png, your spreadsheet should contain EMP001, EMP002, etc.
Link a media album to your template In the editor’s Media tab, select the album to link. This tells Mergram which album to search when resolving image field values.
Change a field’s render type to Image Click any canvas field and change its render type to Image.
Resize the bounding box The image will scale to cover the bounding box width, maintaining its aspect ratio. Adjust the box dimensions to control the image size. The image is aligned to the top-left corner. You can add an optional margin for padding.

Filename Resolution

Mergram resolves image names from spreadsheet cells to album media items:

Case-insensitive matching — Photo1, photo1, and PHOTO1 all match
Stem fallback — photo1.png matches an album item named photo1 (extension stripped)
Missing images — If no match is found, the field is skipped with a warning (the merge does not fail)
Margins — Add padding inside the field bounds

Quick tip

Use the copy filename button in the Media tab sidebar to get exact filenames for your spreadsheet cells. This eliminates typos and mismatched names.

Media Albums

Media Albums organize your images into groups:

Create albums — Group images by project, category, or template
Team-scoped — All team members can access shared albums
Thumbnails — Mergram generates thumbnails for easy browsing
Pagination — Browse large albums with paginated views

Album linking

Each template links to one album at a time. If you need images from multiple sources, combine them into a single album or use a naming convention that avoids conflicts.

Best Practices

Use consistent naming — Match image filenames exactly to your spreadsheet data values
Optimize images before upload — Resize to the display dimensions and compress to reduce file size
Use JPEG for photos — JPEGs are smaller than PNGs for photographic content
Use PNG for logos and graphics — PNGs support transparency and sharp edges
Test with previews — Preview a few rows to verify images render at the correct size and position
Keep album sizes manageable — Organize images into separate albums per project rather than one massive collection

Limitations

PNG and JPEG only — SVG, GIF, BMP, WebP, and TIFF are not supported
10 MB upload limit — Individual images must be under 10 MB
No URL-based images — Images must be uploaded to a Media Album
Single album per template — Each template can link to only one album at a time