These set of options are used to overlay one image over another image. This will help you generate watermarked images if needed.

Let's suppose we want to generate an image like:

The above image comprises of two images - the original image of the cafe and the image of's logo. The logo is overlaid on top of the original image.

Individually, the two images are accessible on the following URLs.

Original image

Overlay logo image

Since the original image acts as the base in the final image to be obtained, we will start with that URL and look at different functionalities related to image overlays.

Specifying the overlay image

 The overlay image is specified using the "oi" transformation parameter. With this parameter, you need to specify the path where the image is accessible.

For example, for the above image, the image path is logo-white_SJwqB4Nfe.png (after removing the URL endpoint i.e. )

So the transformed URL becomes -

Or if you prefer specifying transformation parameters in the query string, then the URL becomes -

For the sake of simplicity, we will stick with the first method of specifying transformation parameters as path parameters.

Overlay images with full image path

If the path of the overlay image contains some folders as well, then replace "/" with "@@" in the path.

For eg:
If the overlay image is at

Then it can be used as an overlay like this -

Changing the position of the overlay image

By default, the overlay image appears right at the centre of the base image. It is very likely that you would want it in a different position. There are two ways of doing it -

1. Position using relative values

In this method, we specify the position of the overlay image as a value relative to the base image using the 'ofo' transformation parameter. For example, if we want the image to be overlaid in the top-left corner, we specify the position as top_left. If we want it at bottom-right corner, we specify the position as bottom_right.

Here is an example placing the overlay image in the top-left corner.,ofo-top_left/medium_cafe_B1iTdD0C.jpg

The supported values are center, centre (default), top, left, bottom, right, top_left, top_right, bottom_left, bottom_right.

2. Position using absolute coordinates
This method allows us to specify the exact x and y value for placing the overlay image. These coordinates are specified using the 'ox' and 'oy' coordinates. The x,y values are computed between the top-left corner of the base image and the top-left corner of the overlay image.

Here is an example of placing the overlay image at 10px from the left image and 20px from the top image.,ox-10,oy-20/medium_cafe_B1iTdD0C.jpg

You can also specify negative X and Y values. A negative X value is calculated between the right edge of the image and the right edge of the overlay image. A negative Y value is calculated between the bottom edge of the image and the bottom edge of the overlay. To specify the negative values, prepend the pixel distance value with "N".

Here is an example of overlaying an image at 10px from the right and 20px from the top of the base image.,ox-N10,oy-20/medium_cafe_B1iTdD0C.jpg

Another example of overlaying the image at 10px from the right and 20px from the bottom edge.,ox-N10,oy-N20/medium_cafe_B1iTdD0C.jpg

Changing the size of the overlay image

In the above scenario, we are overlaying the logo image as is. And because the base image is decently big in terms of dimensions, the proportion between the two looks fine.

Now, let's say we want to overlay it on to a smaller image, and thus need a smaller logo. We can do resize the overlay image as well directly from the URL, using the parameters 'ow' and 'oh' transformation parameters for overlay width and overlay height respectively.

Here is an example of resizing the overlay image to height 20px and overlaying it at 5px from the bottom edge and 10px from the right edge.,ox-N5,oy-N10,oh-20/medium_cafe_B1iTdD0C.jpg

Let's say if you want to resize the base image and use the resized logo with it, then these two transformations should be used as separate steps in a chain. You can read about chained transformations here. The base image resizing should be done in the first step and the overlay resizing and positioning in the next. The reason for this is that the overlay positions would then be calculated corresponding to the resized image from the first step.

Here is an example of resizing the base image to width 300px using the 'w' transformation and then overlaying the logo image.,ox-N5,oy-N10,oh-20/medium_cafe_B1iTdD0C.jpg

It is recommended that you use either the overlay width (ow) or the overlay height (oh) parameter, and not both together. Using both these parameters together will crop the overlay image.

Trimming of the overlay image

By default, ImageKit trims the overlay image before overlaying it on the base image. For example, consider the image below, which has the same white logo to be overlaid but this time inside a black rectangular box.

ImageKit uses the trim transformation on all overlay images by default. The trim transform is specified here. This would remove all the black padding around the actual white logo.

The final result looks like this

There might be cases where you do not need such trimming to happen. Then, you can do that from the URL itself using the 'oit' parameter and specifying it as false.,oit-false/medium_cafe_B1iTdD0C.jpg

If you have any questions or a feature request for overlay images, then please contact us at


Did this answer your question?