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

The `x-fastly-imageopto-overlay` header overlays one image on top of another image.

> **IMPORTANT:** Unlike most IO parameters, overlays must be specified using an HTTP header, rather than via the query string of the client request.

## Syntax

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

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

## Sub-parameters

| Param                                    | Description                                                                                                                                                                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `overlay`                                | Root-relative URL.                                                                                                                                                                                                                         |
| `overlay-base64`                         | Base64 encoded root-relative URL.                                                                                                                                                                                                          |
| `overlay-width`                          | Width of the overlay image. When specified as a percentage, the width is relative to the output image.                                                                                                                                     |
| <nobr><code>overlay-height</code></nobr> | Height of the overlay image. When specified as a percentage, the height is relative to the output image.                                                                                                                                   |
| `overlay-align`                          | The position of the overlay relative to the image, in the form `{y-align},{x-align}`. For `{y-align}`, choose from `top`, `middle`, and `bottom`. For `{x-align}`, choose from `left`, `center`, and `right`. Defaults to `middle,center`. |
| `overlay-pad`                            | Add padding to the edges of the overlay. Takes the same form as [`pad`](https://www.fastly.com/documentation/reference/io/pad).                                                                                                            |
| `overlay-repeat`                         | How the overlay should be repeated. Choose from `x`, `y`, or `both`.                                                                                                                                                                       |

## Examples

Align the overlay to the top of the source image:

```vcl context="sub vcl_recv { ... }"
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-align=top";
```

Align the overlay to the bottom-right:

```vcl context="sub vcl_recv { ... }"
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-align=bottom,right";
```

Resize the overlay to be 75% the height of the output image, and pad it - on the top and bottom edge by 25px, and on the right and left edge by 50px:

```vcl context="sub vcl_recv { ... }"
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-height=0.75&overlay-pad=25,50";
```

Tile an overlay across the source image:

```vcl context="sub vcl_recv { ... }"
set req.http.X-fastly-imageopto-overlay = "overlay=/img/overlay.png&overlay-repeat=both";
```