# Images and Links for Code Templates


Images and links are fundamental building blocks of most PDFMonkey templates. This page walks you through each way to include visual assets and clickable links in your PDFs.

## Including Images

There are three ways to include images in your templates. Here is a quick comparison to help you pick the right one:

| Method                                | Works on Free plan | Needs external hosting | Best for                                        |
| ------------------------------------- | ------------------ | ---------------------- | ----------------------------------------------- |
| [URL-based images](#url-based-images) | No (paid only)     | Yes                    | Most use cases: product photos, dynamic content |
| [Embedded images](#embedded-images)   | Yes                | No                     | Small static assets like logos or signatures    |
| [Inline SVG](#inline-svg)             | Yes                | No                     | Icons, simple graphics                          |

### URL-Based Images

The most common approach is to reference images by URL. If your images are hosted somewhere (a CDN, your own server, a cloud storage bucket), just point to them.

> [!WARNING]
> **Paid account only**
>
> Including images by URL is only available on paid accounts. Documents that reference external images will fail on a free account. See [External Resources](../getting-started/external-resources.md) for details. If you are on a free plan, see [Embedded images](#embedded-images) below.


**Static image.** Hard-code the URL in your template:

```html title="HTML"
<img src="https://placekitten.com/200/300" />
```

**Dynamic image.** Pass the URL in your payload and reference it in the template.

Payload:

```json
{
  "imageUrl": "http://placekitten.com/200/300"
}
```

Template:

```html title="HTML"
<img src="{{imageUrl}}" />
```

**Background image.** Define a background image in the CSS tab:

```css title="CSS"
.some-class {
  background-image: url("https://placekitten.com/200/300");
}
```

Then apply it to any element in your HTML tab:

```html title="HTML"
<div class="some-class">...</div>
```

**Dynamic background image.** You cannot use dynamic data from the CSS tab the way you do in the HTML tab. But you have two options.

You can use inline styling:

```html title="HTML"
<div style="background-image: url('{{imageUrl}}');">...</div>
```

Or you can use an inlined `<style>` block in your HTML tab:

```html title="HTML"
<style>
  .some-class {
    background-image: url("{{imageUrl}}");
  }
</style>

<div class="some-class">...</div>
```

You could also use [the CSS custom properties technique](./custom-css.md#the-css-custom-properties-technique) if you want to keep all your CSS in the CSS tab.

### Embedded Images

If you don't have images hosted online, or if you are on a free plan, you can embed image data directly in your template or API payload. The image is self-contained, so nothing is fetched from the internet at generation time.

**How it works:** you provide the image as a text string that contains the full image data (technically called a "data URI"). It looks like a long `data:image/png;base64,R0lGODlhE...` string. You don't need to understand the format, just produce the string and use it as the image source.

> [!NOTE]
> **How to get an embedded image string**
>
> Search for "image to data-URI converter" online. You'll find free tools that let you upload an image and get the string back, ready to paste.


**Static image.** For an image that never changes (a company logo, a decorative element), paste it directly in your template:

```html title="HTML"
<img src="data:image/png;base64,R0lGODlhE...UjIQA7" />
```

**Dynamic image.** If the image comes from your application (a user photo, a signature), send it in your payload and reference it in the template.

Payload:

```json
{
  "imageUrl": "data:image/png;base64,R0lGODlhE...UjIQA7"
}
```

Template:

```html
<img src="{{imageUrl}}" />
```

> [!TIP]
> **Keep embedded images small**
>
> Since the image data lives inside your template or payload, large images can make things unwieldy. Embedded images work best for small assets like logos or signatures. For larger or frequently changing images, [URL-based images](#url-based-images) are a better fit.


### Inline SVG

For icons, simple shapes, or graphics you control at the code level, you can insert SVG markup directly in your HTML:

```html title="HTML"
<svg height="100" width="100">
  <circle cx="50" cy="50" r="40" stroke="purple" stroke-width="3" fill="pink" />
</svg>
```

Because inline SVG is part of the template itself, it works on every plan and loads instantly.

## Performance Tips

If you are concerned about generation speed, using smaller images is the single most impactful improvement. Smaller images load faster, which means faster document generation.

Favor modern formats that produce lightweight files. PDFMonkey supports [WebP](https://developers.google.com/speed/webp) and [AVIF](https://en.wikipedia.org/wiki/AVIF). Free online converters can help you shrink images without visible quality loss.

Embedded images and inline SVG skip network requests entirely, which also helps. But even for those, optimizing the image data is beneficial.

If you prefer classic formats like JPEG or PNG, use a tool like [ImageOptim](https://imageoptim.com/) to reduce file sizes.

> [!NOTE]
> **Looking for file size optimization?**
>
> If your generated documents are larger than expected, see [Image Resolution and File Weight](./image-weight-and-resolution.md) for a detailed guide on why images inflate PDF size and how to fix it.


## Using Links in PDFs

You can use both internal and external links in your documents.

### Internal Links

If you want to link to specific sections of your PDF, it works just like in a regular web page. Start by defining an anchor you want to link to:

```html
<div id="some-section">
  <!-- your content goes here -->
</div>
```

Then link to it from elsewhere in the content:

```html
<a href="#some-section">Go to Some Section</a>
```

### External Links

You can link to any web page on the internet by defining a link:

```html
<a href="https://www.pdfmonkey.io">Visit our website</a>
```

> [!NOTE]
> **You don't need target="_blank"**
>
> Since your link is rendered in a PDF, adding `target="_blank"` is not necessary. It works when viewing the PDF in a web-based viewer (like our preview) but is ignored in most contexts.



## FAQ

**How do I add images to a PDFMonkey template?**

Three ways: URL-based images (reference images hosted on a CDN or server — paid plans only), embedded images as Base64 data URIs (works on all plans, best for small assets like logos), and inline SVG for icons and simple graphics.

**Can I use images on the PDFMonkey free plan?**

Yes, but only embedded Base64 images or inline SVG. URL-based images require a paid plan because they rely on external resources. See the External Resources page for details.

**How do I add a dynamic image from my API payload in PDFMonkey?**

Pass the image URL in your JSON payload (e.g., {"imageUrl": "https://example.com/photo.jpg"}) and reference it in your template with an img tag: <img src="{{imageUrl}}" />.
