---
title: x-fastly-imageopto-montage
summary: null
url: https://www.fastly.com/documentation/reference/io/montage
---




The `x-fastly-imageopto-montage` header adds the ability to combine up to four images into a single image, based on a predefined set of layout templates.

> **IMPORTANT:** If an `x-fastly-imageopto-montage` header is specified, all other IO parameters and headers are ignored. Also, unlike most IO parameters, montage must be specified using an HTTP header, rather than via the query string of the client request.


## Syntax

```text
x-fastly-imageopto-montage: {param-list}
```

`{param-list}` is a query string-encoded set of key-value pairs.

## Sub-parameters

|Param	|Description|
|-------|-----------|
| `width`    | Width of the output image as a whole number of pixels. |
| `height`   | Height of the output image as a whole number of pixels. |
| `layout`   | A template (see template layouts below). |
| `images`   | A semicolon-separated list of root-relative image URLs.|
| `dpr`      | Device Pixel Ratio. *(optional)* |
| `padding`  | Add additional pixels to the inside edges of an image. *(optional)*|
| `bg-color` | Background color of the output image, as a 3- or 6-digit hexadecimal RGB value, to use when applying padding. *(optional)*|
| `format`   | The output image format. *(optional)*|
| `quality`  | Output image quality for lossy file formats. *(optional)*|

## Template Layouts

<div class="grid" style="margin-bottom: 1em">
  <div class="span3">
    <code>2a</code><br/>
    <div class={styles.template} style='grid: "a" 1fr "b" 1fr / 1fr'><span>1</span><span>2</span></div>
  </div>
  <div class="span3">
    <code>2b</code><br/>
    <div class={styles.template} style='grid: "a b" 1fr / 1fr 1fr'><span>1</span><span>2</span></div>
  </div>
  <div class="span3">
    <code>3a</code><br/>
    <div class={styles.template} style='grid: "a" 1fr "b" 1fr "c" 1fr / 1fr'><span>1</span><span>2</span><span>3</span></div>
  </div>
  <div class="span3">
    <code>3b</code><br/>
    <div class={styles.template} style='grid: "a a" 2fr "b c" 1fr / 1fr 1fr;'><span>1</span><span>2</span><span>3</span></div>
  </div>
  <div class="span3">
    <code>3c</code><br/>
    <div class={styles.template} style='grid: "a b" 1fr "a c" 1fr / 2fr 1fr'><span>1</span><span>2</span><span>3</span></div>
  </div>
  <div class="span3">
    <code>3d</code><br/>
    <div class={styles.template} style='grid: "a b c" 1fr / 1fr 1fr 1fr'><span>1</span><span>2</span><span>3</span></div>
  </div>
  <div class="span3">
    <code>4a</code><br/>
    <div class={styles.template} style='grid: "a" 1fr "b" 1fr "c" 1fr "d" 1fr / 1fr'><span>1</span><span>2</span><span>3</span><span>4</span></div>
  </div>
  <div class="span3">
    <code>4b</code><br/>
    <div class={styles.template} style='grid: "a b" 1fr "c d" 1fr / 1fr 1fr'><span>1</span><span>2</span><span>3</span><span>4</span></div>
  </div>
  <div class="span3">
    <code>4c</code><br/>
    <div class={styles.template} style='grid: "a a a" 3fr "b c d" 1fr / 1fr 1fr 1fr;'><span>1</span><span>2</span><span>3</span><span>4</span></div>
  </div>
  <div class="span3">
    <code>4d</code><br/>
    <div class={styles.template} style='grid: "a b" 1fr "a c" 1fr "a d" 1fr / 3fr 1fr;'><span>1</span><span>2</span><span>3</span><span>4</span></div>
  </div>
  <div class="span3">
    <code>4e</code><br/>
    <div class={styles.template} style='grid: "a b c d" 1fr / 1fr 1fr 1fr 1fr;'><span>1</span><span>2</span><span>3</span><span>4</span></div>
  </div>
</div>


## Notes

1. By default, all images will fill the area by cropping from the center of the image.
2. The maximum number of images currently supported is 4.
3. An image montage is counted as 1 image optimization request regardless of how many images the montage contains. However, on a cache miss each sub image will count as a non-IO request.

## Examples

This VCL:

```vcl context="sub vcl_recv { ... }"
set req.http.x-fastly-imageopto-montage = "" +
  "width=500&height=500&layout=2a&images=/image1.jpg;/image2.jpg";
```

will result in:

![/io-demo/montage/2a](https://developer.fastly.com/io-demo/montage/2a)

**Advanced**

This VCL:

```vcl context="sub vcl_recv { ... }"
set req.http.x-fastly-imageopto-montage = "" +
  "width=500&height=500&layout=2b&images=/image1.jpg;/image2.jpg"
  "&" if(req.url.qs ~ "(?:^|&)(bg-color=[^&]+)", re.group.1, "")
  "&" if(req.url.qs ~ "(?:^|&)(dpr=[^&]+)", re.group.1, "")
  "&" if(req.url.qs ~ "(?:^|&)(quality=[^&]+)", re.group.1, "")
  "&" if(req.url.qs ~ "(?:^|&)(format=[^&]+)", re.group.1, "")
  "&" if(req.url.qs ~ "(?:^|&)(padding=[^&]+)", re.group.1, "")
;
```

will result in:

![/io-demo/montage/2b?padding=10&bg-color=000&format=png](https://developer.fastly.com/io-demo/montage/2b?padding=10&bg-color=000&format=png)