How do I add an image to a PDFMonkey builder template?

Drag an Image block from the Blocks panel onto the canvas. In the Settings tab, you can paste a static URL, upload a file from your computer, or bind the source to a variable in your document data for dynamic images.

Can I use dynamic images that change per document in PDFMonkey?

Yes. Click the variable browser button (curly braces icon) in the Image Settings panel and select a data path like company.logo or user.avatar_url. Each generated document will pull its image from the payload data you provide.

What is the recommended file size for uploaded images in PDFMonkey?

Keep uploaded images under 200 KB. Uploaded files are embedded as data URIs inside the template, so large images increase template size and slow down both saving and PDF generation. For larger images, host them on a server and use a URL instead.

How do I add a background image to an element in the PDFMonkey builder?

Select any element, switch to the Styles tab, and expand the Background section. Set a Background Image URL or data binding, then configure repeat, size, and position settings to control how the image displays behind the element’s content.

Images

Images are one of the most common elements in PDF templates — logos, product photos, avatars, charts. The builder gives you three ways to set an image source: paste a URL, upload a file, or bind the source to a variable in your document data.

Adding an image block

Open the Blocks panel on the left side of the builder and look under the Content category. Drag an Image block onto the canvas or click it to add it inside the currently selected container.

The Image block selected within the blocks list

When you select the Image block, the right panel switches to the Settings tab where you’ll find the Image Settings section with a URL input field.

Setting the image source

The Image Settings section shows a URL input field with two buttons on the right: a variable browser button (curly braces icon) and an upload button (upload icon).

The Image Settings panel showing the URL input with variable browser and upload buttons

Static URL

Type or paste a full URL (starting with https://) directly into the input field and press Enter or click away. The image loads immediately in the canvas preview.

https://example.com/logo.png

Paid accounts only

Including images based on their URL is only possible on a paid account or during the trial period. Documents including external images will fail on a free account. See External Resources for the full list.

Upload a file

Click the upload button (upload icon) to open a file picker. Select an image file from your computer. The builder converts it to a data URI and embeds it directly in the template.

Watch the file size

Uploaded images are embedded as data URIs inside the template. Large images:

increase the template size,
slow down PDF generation,
make saving the template noticeably slower since the full content is sent every time.

Keep uploaded images under 200 KB when possible. For larger images, host them on a server and use a static URL instead.

After uploading, the input is replaced by a thumbnail preview of the image with buttons to replace or remove it.

Dynamic binding

Click the variable browser button (curly braces icon) to open a dropdown listing all available data paths from your test data. Select a path that contains an image URL — for example, company.logo or user.avatar_url.

The variable browser dropdown showing available data paths

You can also type a variable path directly into the input field. The builder automatically detects that a value like company.logo is a data binding (not a URL) and treats it accordingly.

The variable browser only shows paths that exist in your current test data. If you don’t see the path you need, open the test data editor and add the relevant field with a sample image URL.

Background images

Any element in the builder — not just Image blocks — can have a background image. Select an element, switch to the Styles tab in the right panel, and expand the Background section.

The Background section includes:

Setting	What it controls
Background Color	Solid color behind the element
Background Image	An image URL or data binding for the background
Background Repeat	Whether the image tiles (`repeat`, `no-repeat`, etc.)
Background Size	How the image scales (`cover`, `contain`, or a specific size)
Background Position	Where the image anchors (`center`, `top left`, etc.)

Use background images when you need an image behind other content — for example, a watermark, a decorative header, or a full-page background pattern.

Tips for working with images

Keep file sizes reasonable. Large images slow down PDF generation. Resize and compress images before using them.
Use URLs for images that change. If the image differs per document (a customer logo, a product photo), use a dynamic binding so each generated PDF pulls the correct image from your data.
Use uploads for images that stay the same. If the image is always identical across documents (your company logo at a fixed size), uploading keeps things simple and avoids external dependencies.
Check CORS for external URLs. Images loaded from external servers must allow cross-origin requests. If an image fails to render in the generated PDF, check whether the hosting server supports CORS.

Frequently asked questions

How do I add an image to a PDFMonkey builder template?: Drag an Image block from the Blocks panel onto the canvas. In the Settings tab, you can paste a static URL, upload a file from your computer, or bind the source to a variable in your document data for dynamic images.
Can I use dynamic images that change per document in PDFMonkey?: Yes. Click the variable browser button (curly braces icon) in the Image Settings panel and select a data path like company.logo or user.avatar_url. Each generated document will pull its image from the payload data you provide.
What is the recommended file size for uploaded images in PDFMonkey?: Keep uploaded images under 200 KB. Uploaded files are embedded as data URIs inside the template, so large images increase template size and slow down both saving and PDF generation. For larger images, host them on a server and use a URL instead.
How do I add a background image to an element in the PDFMonkey builder?: Select any element, switch to the Styles tab, and expand the Background section. Set a Background Image URL or data binding, then configure repeat, size, and position settings to control how the image displays behind the element’s content.