Overlay

A comprehensive guide that covers how you can overlay images and text over another image.

Image overlay

Overlay image - (oi)

Used to overlay an image on top of another image (base image). This helps you generate watermarked images.

Let's say base image URL is - https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg

Overlay image logo URL is - https://ik.imagekit.io/demo/logo-white_SJwqB4Nfe.png

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. ImageKit.io currently supports JPEG/JPG and PNG images for overlay.

  2. The overlay image path should be accessible using your ImageKit.io account.

Final URL - https://ik.imagekit.io/demo/tr:oi-logo-white_SJwqB4Nfe.png/medium_cafe_B1iTdD0C.jpg

URL structure
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

Controlling the position of overlay image

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

Controlling the dimension of overlay image

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

Trimming of the overlay image

By default, ImageKit.io trims the overlay image before overlaying it on the base image. 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.

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 Background - (obg)

If you want to overlay a solid color block over a base image, use obg parameter. Possible Values- Valid RGB Hex Code with optional alpha component

For example - 00AAFF (solid color) or 00AAFF55 (with 55% opacity)

Overlay Background Transparency is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99.

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 .

Overlay focus - (ofo)

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 Valuecenter

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 trimming - (oit)

Used to trim overlay images. This removes the transparency of the overlaid image. Default Valuetrue

Learn more from example here.

Text overlay

Overlay text - (ot)

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

Base image
Text overlay example

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. The base64 string should be made URL safe to ensure that all padding characters(=) are included correctly. A function like encodeUri() can be used for this.

  2. Input above the length of 144 characters will be truncated.

Example URL - https://ik.imagekit.io/demo/tr:ote-b3ZlcmxheSBtYWRlIGVhc3k%3D,ots-45/medium_cafe_B1iTdD0C.jpg

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.

Example URL - https://ik.imagekit.io/demo/tr:ot-overlays%20made%20easy,ots-45,otc-00FFFF,otw-200/medium_cafe_B1iTdD0C.jpg

Overlay text background - (otbg)

If you want to give the text block a solid background color (and transparency), use this parameter.

Possible Values - Valid RGB Hex Code with optional alpha component

Example values - 00AAFF (solid color) or 00AAFF55 (with 55% opacity)

Overlay text background transparency

This is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99.

With solid color background
Solid color background with transparency

Overlay text padding - (otp)

To specify the padding around the overlaid text on the image.

Possible values include any positive integer.

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)

To specify the color and transparency of the overlaid text on the image.  Possible Values: Valid RGB Hex Code with optional alpha component

For example - 00AAFF (solid color) or 00AAFF55 (with 55% opacity)

Overlay Text Transparency is supported via alpha component in RGB hex code which takes a numeric value between 00 and 99.

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.

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
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 transparency - (oa)

To specify the transparency level of the overlaid image.  Possible Values include integers from 1  to 9 . Note: Overlay Transparency is currently supported for overlay texts. It applies to overlay backgrounds only if alpha component is not set in obg parameter.