> ## Documentation Index
> Fetch the complete documentation index at: https://docsautomator.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Images

> Insert images dynamically into your documents from URLs or attachments

DocsAutomator enables image insertion throughout documents. Images are automatically preprocessed, converted, and can be resized to optimize document quality and file size.

<Warning>
  Passed images need to be publicly available on the web.
</Warning>

## Syntax

Images are declared using the `image_` prefix:

```
{{image_variableName}}
```

<CodeGroup>
  ```text Examples theme={null}
  {{image_headshot}}
  {{image_product}}
  {{image_companyLogo}}
  {{image_signature}}
  ```
</CodeGroup>

This tells DocsAutomator where to insert images. You can pass single or multiple images, which are added inline within the document.

## Pre-processing & Converting

The system optimizes images before insertion:

* **Format conversion**: Images are automatically converted to .jpg format
* **Quality optimization**: Reduces file size while maintaining quality
* **PNG exception**: PNG files retain their format to preserve transparency

### Supported Formats

JPG, PNG, GIF, BMP, TIFF, ICO, PDF (first page), EPS, AI, PSD, SVG, WebP, AVIF, HEIF, JXR, WDP

<Note>
  If a placeholder value contains non-image content (such as HTML, plain text, or an unsupported file type), it will be silently skipped and the placeholder will be removed from the document. This ensures that invalid data in image fields never causes the entire document generation to fail.
</Note>

### Image Quality Settings

Configure image handling in **Template / Document Generation Options**:

| Setting | Description                                  |
| ------- | -------------------------------------------- |
| Low     | Smallest file size, lower quality            |
| Eco     | Balanced quality and file size (recommended) |
| Good    | Higher quality, larger file size             |
| Best    | Maximum quality, largest file size           |

### Maximum Width

* Range: 200-2000 pixels
* Standard: 600px
* Example: An 8000×6000px image resizes to 600×450px

<Tip>
  The "Eco" setting is recommended for balanced quality and file size in most use cases.
</Tip>

## Resizing Images

Resize individual placeholder images through DocsAutomator's interface:

* **Aspect ratio**: Always preserved during resizing
* **Single dimension**: Other dimension calculates automatically to maintain proportions
* **Both dimensions**: Image scales to fit while preserving aspect ratio

<Warning>
  If the resizing parameter exceeds the maximum width in automation settings, the image will be expanded and lose quality.
</Warning>

## Clickable Image Links

Turn any image into a clickable hyperlink. Open the placeholder's image options, enable **Linked image**, and choose where the target URL comes from. The link is applied to the image and survives PDF export.

<Tabs>
  <Tab title="Airtable, Google Sheets, SmartSuite, ClickUp">
    Pick the field or column whose value holds the target URL. The URL is resolved per record, so every generated document links to the right place.
  </Tab>

  <Tab title="API, Zapier, Make, n8n, Glide, Noloco, MCP">
    These sources have no field list to pick from, so you have two options:

    * **Pass the link inline** (direct API or MCP): send the image value as a `{ "url", "link" }` object instead of a plain URL string. No setup is required. See [Passing Images via API](#passing-images-via-api) below.
    * **Reference another placeholder** (no-code tools): map the URL to a separate placeholder, select it as the link source in the image options, and hide that placeholder so it does not also render as text.
  </Tab>
</Tabs>

Clickable image links work in both Google Doc and Word (.docx) templates.

## Passing Images via API

When using the DocsAutomator API, pass an array of image URLs for processing:

```json theme={null}
{
  "docId": "your-automation-id",
  "data": {
    "image_product": "https://example.com/product.jpg",
    "image_signature": "https://example.com/signature.png"
  }
}
```

### Clickable Images via API

To make an image clickable, pass it as a `{ "url", "link" }` object instead of a plain URL string. The `url` is the image and the `link` is where it points. No automation setup is required, and the link survives PDF export (Google Doc and Word templates):

```json theme={null}
{
  "docId": "your-automation-id",
  "data": {
    "image_product": {
      "url": "https://example.com/product.jpg",
      "link": "https://shop.example.com/products/123"
    }
  }
}
```

This works for single images and for arrays, where each image can carry its own `link`:

```json theme={null}
{
  "image_gallery": [
    { "url": "https://example.com/a.jpg", "link": "https://shop.example.com/a" },
    { "url": "https://example.com/b.jpg", "link": "https://shop.example.com/b" }
  ]
}
```

## Multiple Images

To insert multiple images for a single placeholder, pass them as an array or comma-separated URLs depending on your data source:

<Tabs>
  <Tab title="API">
    ```json theme={null}
    {
      "image_gallery": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg",
        "https://example.com/image3.jpg"
      ]
    }
    ```
  </Tab>

  <Tab title="Google Sheets">
    Separate multiple image URLs with commas in your spreadsheet cell.
  </Tab>

  <Tab title="Airtable">
    Use an Attachment field with multiple images.
  </Tab>
</Tabs>

## Choosing Which Image to Insert

When a placeholder receives multiple images, you can choose which of them end up in the document. Open the placeholder's image options and set **Which image**:

| Option               | Behavior                         |
| -------------------- | -------------------------------- |
| All images (default) | Every image is inserted inline   |
| First image only     | Only the first image in the list |
| Last image only      | Only the last image in the list  |

The setting is per placeholder and works with every data source and template type. Width and height settings apply to whichever image is inserted.

<Tip>
  "First" and "last" follow the order of the images in your data source. In Airtable, that's the attachment order in the field, which you can change by dragging, so you control exactly which image is picked no matter how many are attached.
</Tip>

<Note>
  Word templates insert a single image per placeholder: "First image only" and "Last image only" work as described, and a multi-image field left on "All images" inserts the first image. Google Doc templates insert all images inline.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Use publicly accessible image URLs" icon="globe">
    Image placeholders expect valid, publicly accessible image URLs. If a value is not a valid image (e.g. HTML, plain text, or a broken link), the image will be skipped and the placeholder removed from the document.
  </Accordion>

  <Accordion title="Optimize source images" icon="compress">
    While DocsAutomator compresses images, starting with reasonably sized images improves processing speed.
  </Accordion>

  <Accordion title="Use PNG for transparency" icon="square">
    If your image requires transparency (logos, overlays), use PNG format.
  </Accordion>

  <Accordion title="Test with preview mode" icon="eye">
    Always test image rendering in preview mode before production.
  </Accordion>
</AccordionGroup>

## Related Pages

<CardGroup cols={2}>
  <Card title="Template Guide" icon="file-lines" href="/docsautomator-basics/google-doc-template-guide">
    Learn all template syntax
  </Card>

  <Card title="Line Items" icon="list" href="/features/line-items">
    Add images in repeating rows
  </Card>
</CardGroup>