ImageKit.io Docs
PricingService statusDashboardWe are hiring 🤓
Search
⌃K
Links
Comment on page

Overlay (deprecated)

A comprehensive guide that covers how you can overlay images and text over another image.
Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.

Introduction about overlays

You can overlay images or text over other images for watermarking or creating a dynamic banner using custom text.
Overlay logo over another image
The above image is created using below URL:
Let's first understand what all is possible in overlay and then you can deep dive into different options available based on what you need. To help you understand, we have added many examples in this documentation.

Position of overlay image

You can control the position of overlay image relative to base image using overlay focus (ofo), overlay X position (ox) or overlay Y position (oy).

Dimension of overlay image

You can control the dimension of overlay image using overlay height (oh) and overlay width (ow).

Related blog post for creating photo collage

Common overlay options

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
The following options are available for both image and text overlay.

Overlay X position - (ox)

Used to provide granular control over the position of the overlay image relative to the base image.
The top left corner of the input image is considered as (0,0), and the bottom right corner as (w,h), where w is the width and h is the height of the input image. If ox is 100, then the overlay image is placed at 100px from the left edge of the input image. If the ox value exceeds the dimensions of the input image, the values are adjusted and made equal to the corresponding dimension of the input image. Negative values are also supported with a leading N in front of the provided value.
Possible Values include any positive integer. If prefixed with N , then treated as a negative integer.

Overlay Y position - (oy)

Used to provide granular control over the position of the overlay image relative to the base image.
The top left corner of the input image is considered as (0,0), and the bottom right corner as (w, h), where w is the width and h is the height of the input image. If oy is 150, then the overlay image is placed at 150px from the top edge of the input image. If the oy value exceeds the dimensions of the input image, the values are adjusted and made equal to the corresponding dimension of the input image. Negative values are also supported with a leading N in front of the provided value.
Possible Values include any positive integer. If prefixed with N , then treated as a negative integer.

Overlay height - (oh)

Used to specify the height of the overlay image.
Using both oh and ow parameters together will crop the overlay image.

Overlay width - (ow)

Used to specify the width of the overlaid image.
Using both oh and ow parameters together will crop the overlay image.

Overlay Background - (obg)

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
If you want to overlay a solid color block over a base image, use obg parameter. Possible Values
  • RGB Hex code: A 6-digit hex code (eg. AAFF00, 0f0fac)
  • RGBA Hex code: An 8-digit hex code. Last two characters must be a number between 00 and 99, specifying the opacity level (eg. AAFF0040, 0f0fac75)
  • Color name: A standard color name in lowercase (eg. lightgreen, beige)

Overlay Background Transparency

This is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99, or via oa.
If both obg and oa are set in a single transformation and obg has an alpha component, then that value is used to set overlay background transparency. Otherwise, oa value is used. If obg is set to a standard color name (eg. blue), then the oa value is ignored.

Overlay focus - (ofo)

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
You can control the relative position of overlay image using ofo parameter. This position is relative to base image.
Possible values include center , top , left , bottom , right , top_left , top_right , bottom_left , and bottom_right . Default Value - center

Image overlay

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.

Overlay image - (oi)

Used to overlay an image on top of another image (base image). This helps you generate watermarked images.
Now to overlay this logo over the base image we will pass the path of overlay image in oi parameter i.e. logo-white_SJwqB4Nfe.png
  1. 1.
    ImageKit.io currently supports JPEG/JPG and PNG images for overlay.
  2. 2.
    The overlay image path should be accessible using your ImageKit.io account.
URL structure
overlay image path base image path
┌──────────────────────┐┌───────────────────────┐
{url-endpoint}/tr:oi-logo-white_SJwqB4Nfe.png/medium_cafe_B1iTdD0C.jpg

Using overlay image that are stored in a nested folder

In the above example, overlay image logo was stored in home folder i.e. /, so there was no slash in the overlay image path. However it could be possible that you have overlay images stored within a specific folder, in that case there will be slashes (/) in overlay image path. To overcome this you need to replace slash / with @@.
For example, if the overlay image is at https://ik.imagekit.io/demo/path/to/overlay.jpg
Then it can be used as an overlay like below:
https://ik.imagekit.io/demo/tr:oi-path@@to@@overlay.jpg/medium_cafe_B1iTdD0C.jpg

Trimming of the overlay image

By default, ImageKit.io trims the overlay image before overlaying it on the base image. Trimming removes the similar colored pixels from the edges. By default, overlay image is trimmed.
There might be cases where you do not need such trimming to happen. Then, you can do that from the URL itself using the overlay trim (oit) parameter and specifying it as false.
Possible values include true , false and integer values between 1 and 99 that specify the threshold level for considering a particular pixel as "background".
For example, consider the image below, which has the same white logo to be overlaid but this time inside a black rectangular box.
Overlay image logo with black rectangular box - https://ik.imagekit.io/demo/logo_white_black_bg.png​

Overlay image aspect ratio (oiar)

It is used to specify the aspect ratio of the overlay image or the ratio of width to height of the overlay image.
This parameter must be used along with either the overlay height(oh) or overlay width(ow) parameter. The format for specifying this transformation is oiar-<width>-<height>.
If you specify both overlay height(oh) and overlay width(ow) in the URL along with this parameter, then the overlay image aspect ratio (oiar) is ignored.

Overlay image background (oibg)

It is used to specify the background color that must be used for the overlay image.
Default Value - Black 00000 Possible Values
  • RGB Hex code: A 6-digit hex code (eg. AAFF00, 0f0fac)
  • RGBA Hex code: An 8-digit hex code. Last two characters must be a number between 00 and 99, specifying the opacity level (eg. AAFF0040, 0f0fac75)
  • Color name: A standard color name in lowercase (eg. lightgreen, beige)

Overlay image border (oib)

This adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border.
Usage - oib-<border-width>-<hex code>
The width is specified as a number that is equivalent to the border width in pixels. The color code is specified as a 6-character hex code RRGGBB.

Overlay image DPR (oidpr)

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
It is used to specify the device pixel ratio that is used to calculate the dimensions of the overlay image. Extremely helpful when creating image transformations for devices with high device pixel ratio (DPR > 1), like the iPhone or high-end Android devices.
The oidpr parameter can only be used when either the height or width of the desired output overlay image is specified. If the output image's height or width after considering the specified DPR is less than 1px or greater than 5000px, the value of oidpr is not considered and the overlay height or width used in the URL is used.
Possible Values - 0.1 to 5 .

Overlay image quality (oiq)

It is used to specify the quality of the overlay image for lossy formats like JPEG and WebP. A large quality number results in a bigger image file size with high overlay image quality. A small quality number results in a smaller image file size with lower overlay image quality.
Default Value - 80 (can be managed from image settings in dashboard)

Overlay image cropping

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
Cropping in overlay behave the same way as cropping works in ImageKit.io in general. The only difference is that all cropping and focus related parameters are prefixed with oi.
So essentially:

oic-at_least

It works same as c-at_least but used in context of overlay images only.

oic-at_max

It works same as c-at_max but used in context of overlay images only.

oic-force

It works same as c-force but used in context of overlay images only.

oic-maintain_ratio

It works same as c-maintain_ratio but used in context of overlay images only.

oicm-extract

It works same as cm-extract but used in context of overlay images only.

oicm-pad_extract

It works same as cm-pad_extract but used in context of overlay images only.

oicm-pad_resize

It works same as cm-pad_resize but used in context of overlay images only.

oifo

It works same as fo but used in context of overlay images only.

oifo-auto

It works same as fo-auto but used in context of overlay images only.

oifo-custom

It works same as fo-custom but used in context of overlay images only.

oifo-face

It works same as fo-face but used in context of overlay images only.

oix

It works same as x but used in context of overlay images only.

oiy

It works same as y but used in context of overlay images only.

oixc

It works same as xc but used in context of overlay images only.

oiyc

It works same as yc but used in context of overlay images only.

Overlay trimming - (oit)

By default, ImageKit.io trims the overlay image before overlaying it on the base image. Trimming removes the similar colored pixels from the edges. There might be cases where you do not need such trimming to happen. Then, you can do that from the URL using oit-false.
This removes the transparency of the overlaid image. Default Value - true
Learn more from example here.

Text overlay

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.

Overlay text - (ot)

To overlay text on an image. Supported characters include all alphabets, numbers, spaces, _, -, %, !, @, and &.

Overlay text encoded - (ote)

It is similar to overlay text (ot) but it allows you to overlay special unicode characters (e.g. ©, ®, ™ etc.) that you cannot otherwise pass in a URL as plain string. It accepts base64 string.
  1. 1.
    The base64 string should be made URL safe to ensure that all padding characters(=) are included correctly. In Javascript, a function like encodeURIComponent() can be used for this.
  2. 2.
    Input above the length of 144 characters will be truncated.
Here b3ZlcmxheSBtYWRlIGVhc3k%3D is the base64 string for "overlay made easy"

Overlay text width - (otw)

To specify the maximum width (in pixels) of the overlaid text on the image. The text is wrapped so that any words in a line that go beyond the given width are sent to the next line. Height of the text box is calculated automatically based on the total number of lines.
Possible values include any integer.

Overlay text background - (otbg)

If you want to give the text block a background color, use this parameter.
Possible Values
  • RGB Hex code: A 6-digit hex code (eg. AAFF00, 0f0fac)
  • RGBA Hex code: An 8-digit hex code. Last two characters must be a number between 00 and 99, specifying the opacity level (eg. AAFF0040, 0f0fac75)
  • Color name: A standard color name in lowercase (eg. lightgreen, beige)

Overlay Text Background Transparency

This is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99, or via oa.
If both otbg and oa are set in a single transformation and otbg has an alpha component, then this value is used to set overlay text transparency. Otherwise, oa value is used. If otbg is set to a standard color name (eg. blue), then the oa value is ignored.

Overlay text padding - (otp)

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
To specify the padding around the overlaid text on the image.
Possible values include any positive integer or a set of positive integers separated by underscores.
The set of integers follow CSS shorthand order for determining the padding along each side of the overlay. Learn from the examples:
otp=40
otp=40 and otw=300
otp=25_50_75_100
otp=25_75_60
otp=25_75
URL - https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ots-45,otc-000000,otbg-FFFFFF80,otp-40/medium_cafe_B1iTdD0C.jpg​
URL - https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ots-45,otc-000000,otw-300,otbg-FFFFFF80,otp-40/medium_cafe_B1iTdD0C.jpg​
URL - https://ik.imagekit.io/demo/tr:ot-overlay%20made%20easy,ots-45,otc-000000,otbg-FFFFFF80,otp-25_50_75_100/medium_cafe_B1iTdD0C.jpg​
  • Top padding is 25
  • Right padding is 50
  • Bottom padding is 75
  • Left padding is 100
URL - https://ik.imagekit.io/demo/tr:ot-overlay%20made%20easy,ots-45,otc-000000,otbg-FFFFFF80,otp-25_75_60/medium_cafe_B1iTdD0C.jpg​
  • Top padding is 25
  • Right and left paddings are 75
  • Bottom padding is 60
URL - https://ik.imagekit.io/demo/tr:ot-overlay%20made%20easy,ots-45,otc-000000,otbg-FFFFFF80,otp-25_75/medium_cafe_B1iTdD0C.jpg​
  • Top and bottom paddings are 25
  • Right and left paddings are 75

Overlay text inner alignment - (otia)

To specify the alignment of the overlaid text on the image when text is wrapped with overlay text width (otw).
Possible Values include left, right and center (default).

Overlay text color - (otc)

Deprecation notice This is old overlay syntax and will be deprecated on 31st Oct 2023. Starting 1st November 2023, this old syntax URL will start giving 400 bad request error. Please migrate to new layer syntax that supports overlay nesting, provides better positional control, and allows transformation at the layer level. You can start with examples to learn quickly.
To specify the color and transparency of the overlaid text on the image. Possible Values
  • RGB Hex code: A 6-digit hex code (eg. AAFF00, 0f0fac)
  • RGBA Hex code: An 8-digit hex code. Last two characters must be a number between 00 and 99, specifying the opacity level (eg. AAFF0040, 0f0fac75)
  • Color name: A standard color name in lowercase (eg. lightgreen, beige)

Overlay Text Transparency

This is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99, or via oa.
If both otc and oa are set in a single transformation and otc has an alpha component, then this value is used to set overlay text transparency. Otherwise, oa value is used. If otc is set to a standard color name (eg. blue), then the oa value is ignored.

Overlay text font - (otf)

To specify the font of the overlaid text on the image. You can choose any font from this list or use a custom font.

Using custom fonts

You can use a custom font in text overlay. Upload the font file in your media library and pass the path in otf parameter.
Text overlay using custom font
URL - https://ik.imagekit.io/demo/tr:otf-Lacquer-Regular_nGqtVsBJT.ttf,ot-Hello%20World,ots-72,otc-FFF000/default-image.jpg​
Note: ****Here the font-file is available at path /Lacquer-Regular_nGqtVsBJT.ttf in media library. You will need to pass the whole path including extension.

Overlay text size - (ots)

To specify the size of the overlaid text on the image. Possible Values include any integer.

Overlay text typography - (ott)

To specify the typography of the font used for the overlaid image.
Possible Values include bold b and italics i.

Overlay radius - (or)

To add rounded corners to an overlay background, or to print a circular overlay, use this parameter.
Possible Values include any positive integer.
**Note: **Radius cannot exceed half the length of the shorter side of the overlay element. ‌

Overlay transparency - (oa)

To specify the transparency level of the overlaid image. Possible Values include integers from 1 to 9 . Note: This transform is applied only if the corresponding color transform (obg, otc, etc.) is specified as a Hex code and does not have an alpha component.
Previous
Overlay using layers
Next
Image enhancement & color manipulation
Last modified 4mo ago