Getting started

Integration & migration

Image & video API

DAM user guide

API overview

Account

Add overlays on images

A comprehensive guide on adding images and text on top of a base image using ImageKit.


ImageKit enables you to creatively enhance your images by adding overlays such as images, text, or solid color blocks using layers. This guide provides quick links to examples demonstrating these features.

For further details and in-depth examples, refer to the corresponding sections within this guide. Ensure to review the limits on resource-intensive transformations before deploying these features in production.

Add images over image

You can add an image over a base image using the following syntax.

Image overlay syntax

Copy
         URL endpoint         Base image            Image layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-logo.png,l-end

URL - https://ik.imagekit.io/demo/tr:l-image,i-logo-white_SJwqB4Nfe.png,l-end/medium_cafe_B1iTdD0C.jpg

To overlay images stored within a specific folder of your media library, use the complete image path where slashes (/) are replaced with @@.

For example, if the overlay image is at
https://ik.imagekit.io/demo/path/to/overlay.png, then it can be used as an overlay like:
https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-path@@to@@overlay.png,l-end

Control position of image overlay

You can control image layer position using the lx and ly parameters. If the lx or ly value exceeds the dimensions of the input image, the values are adjusted to fit within the image. To change the direction, negative values are also supported by prefixing the value with 'N'.

Learn more about positional parameters in layers.

Apply transformation on image overlay

Inside an image layer, you can apply these supported transformations to the image overlay before it is placed on the base image. You can chain the transformations one after the other to achieve the desired outcome.

For example, let's resize the overlay image to 400x400 and add a yellow background to fill the image layer's background.

URL - https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg

You can also apply additional transformations, such as e-grayscale, to modify the overlay image. Here's an example of turning the overlay image into a grayscale version.

URL - https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,w-400,e-grayscale,cm-pad_resize,bg-yellow,l-end/medium_cafe_B1iTdD0C.jpg

List of supported image transformations in image layers

ParameterDescription
wWidth of the overlay image. It can also accept arithmetic expressions such as iw_div_2, or bw_sub_cw. Learn more about arithmetic expressions here.
hHeight of the overlay image. It can also accept arithmetic expressions such as ih_div_2, or bh_mul_0.8. Learn more about arithmetic expressions here.
arAspect ratio of the overlay image. It can also accept arithmetic expressions such as iar_div_2, or bar. Learn more about arithmetic expressions here.
cCropping method. Accepts force, at_max, and at_least.
cmCrop mode. Supports extract and pad_resize.
foRelative focus area used during cropping. Accepts face, custom, center, top, left, bottom, right, top_left, top_right, bottom_left, and bottom_right. It also supports object-aware cropping.
zIt determines how much to zoom in or out of the cropped area. It must be used along with fo-face. A value less than 1.0 zooms out to include more background surrounding the face, whereas a value larger than 1.0 zooms in to exclude more background surrounding the face. Possible values include any number between 0 to 1 for zoom out, and greater than 1 for zoom in. Its default value is 1.0.
bIt adds a border to the overlay image. It accepts two parameters - the width of the border and the color of the border in format b-<border-width>-<hex code>. It can also accept arithmetic expressions such as bh_mod_5_red, or bw_mul_0.05_FF00FF. Learn more about arithmetic expressions here.
oIt is used to specify the opacity level of the output image. It accepts numerical values ranging from 0 to 100, where 0 would produce a completely transparent image, and 100 would have no effect.
bgIt is used to specify the background color in RGB Hex Code (e.g. FF0000), or an RGBA Code (e.g. FFAABB50), or a color name (e.g. red) that must be used for the image. If you specify an 8-character background, the last two characters must be a number between 00 and 99, which is used to indicate the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.
rtIt is used to specify the degree by which the overlay image must be rotated.
tBy default, ImageKit.io trims the overlay image before overlaying it on the base image. Trimming removes similar colored pixels from the edges. To prevent the default trimming from happening, use t-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".
dprIt is used to specify the device pixel ratio that is used to calculate the dimensions of the overlay image. It can only be used when either the height or width of the desired output image is specified. The possible values are 0.1 to 5, or auto.
qIt is used to specify the quality of the output image for lossy formats like JPEG, WebP, and AVIF. A large quality number indicates a larger output image size with high quality. A small quality number indicates a smaller output image size with lower quality. It can be a whole number between 1 and 100. The default value is 80.
blIt is used to specify the Gaussian blur that must be applied to an image. The value of bl specifies the radius of the Gaussian Blur that is to be applied. The higher the value, the larger the radius of the Gaussian Blur. Accepts integers between 1 and 100.
xIt is used along with cm-extract to specify the X coordinate of the top-left point where the extract must begin. Possible values are integers, or an arithmetic expression such as iw_div_2, or bh_sub_100. Learn more about arithmetic expressions here.
yIt is used along with cm-extract to specify the Y coordinate of the top-left point where the extract must begin. Possible values are integers, or an arithmetic expression such as ih_div_2, or bw_sub_150. Learn more about arithmetic expressions here.
xcIt is used along with cm-extract to specify the X coordinate of the center point of the image to be extracted. Possible values are integers, or an arithmetic expression such as iw_div_3, or ih_div_4. Learn more about arithmetic expressions here.
ycIt is used along with cm-extract to specify the Y coordinate of the center point of the image to be extracted. Possible values are integers, or an arithmetic expression such as iw_div_3, or ih_div_4. Learn more about arithmetic expressions here.
e-grayscaleIt is used to turn an image to a grayscale version.
e-contrastIt is used to automatically enhance the contrast of the image by using the full intensity values that a particular image format allows. This means that the lighter sections of an image become even lighter and the darker sections become even brighter, thereby enhancing the contrast.
e-sharpenIt is used to sharpen the input image, useful when highlighting the edges and finer details within an image. If just the e-sharpen parameter is used, then a default sharpening is performed on the input image. This can be controlled by specifying a number that restricts the extent of sharpening performed, like e-sharpen-<number>.
e-usmIt is used to apply and control unsharp masks on your images. The amount of sharpening can be varied using 4 parameters - radius, sigma, amount, and threshold. This results in perceptually better images compared to using e-sharpen. Only positive floating points are allowed for these 4 parameters. e.g. e-usm-<radius>-<sigma>-<amount>-<threshold>
e-shadowIt is used to apply a shadow effect on the input image. The strength, blur, and geometrical positioning of the shadow can be varied using the following parameters - st, bl, x and y. e.g. e-shadow-st-<value>_bl-<value>_x-<value>_y-<value> (or simply e-shadow to let the shadow take on default values). Learn more about the shadow effect and its parameters here.
e-gradientIt is used to add a linear gradient overlay over an input image. The direction, from color, to color, and the stop point of the gradient can be varied using the following parameters - ld, from, to and sp. e.g. e-gradient-<linear-direction>_<from-color>_<to-color>_<stop-point> (or simply e-gradient to let the gradient take on default values). Learn more about the gradient effect and its parameters here.

Nesting of image layers

A layer can have nested layers up to 3 levels.

Copy
                       Parent image layer
┌──────────────────────────────────────────────────────────────┐
l-image,i-outer.png,l-image,i-inner.png,lfo-top_left,l-end,l-end
                    └──────────────────┬──────────────────┘
                                       │
                              Nested image layer

In the following example, we overlay the resized women-dress.jpeg with a red border on the bottom left corner of the base image and then add the imagekit.io logo on the top right corner of the women-dress.jpeg image. lfo parameter is used to control the position of layer in relative terms.

URL - https://ik.imagekit.io/demo/tr:l-image,i-women-dress.jpeg,h-400,b-10_red,lfo-bottom_left,l-image,i-logo-white_SJwqB4Nfe.png,w-150,lfo-top_right,l-end,l-end/medium_cafe_B1iTdD0C.jpg

Add text over image

You can add any text string over a base image using the following syntax.

You can also control the position of the text overlay using these positional parameters.

Specified with the i- parameter in a text layer. Supported characters include:

  • All alphabets and numbers (including Unicode letters, marks, and numerals in other languages)
  • Spaces
  • Special characters including _, -, %, !, @, and &
Copy
         URL endpoint         Base image           Text layer
┌──────────────────────────┐┌────────────┐    ┌──────────────────┐
https://ik.imagekit.io/demo/base-image.jpg?tr=l-text,i-hello,l-end

Plain text input longer than 2000 characters will be truncated.

Let's overlay a text overlay made easy on top of medium_cafe_B1iTdD0C.jpg.

https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,fs-45,l-end/medium_cafe_B1iTdD0C.jpg

Control position of text overlay

You can control text layer position using the lx and ly parameters. To change the direction, negative values are also supported by prefixing the value with 'N'.

Learn more about positional parameters in layers.

Apply transformation on text overlay

You can control the width, font size, font family, color, inner alignment, padding, transparency level, typography, background color, corner radius, rotation, and line height of the text overlay using these supported transformations parameters.

For example, let's add a white background with padding and a bigger font size.

You can add padding to the text overlay using the pa parameter. The padding can be controlled individually for each side using the CSS shorthand notation.

Change font family in text overlay

You can change the font family in the text overlay using the ff parameter. You can use the standard fonts available in ImageKit or upload your custom font file to use it in text overlays.

To use a custom font in text overlays, upload the font file in your media library and pass its path in the ff parameter in a text layer.

For example, Lacquer-Regular_nGqtVsBJT.ttf is a custom font file uploaded to the root of the media library and accessible at the URL https://ik.imagekit.io/demo/Lacquer-Regular_nGqtVsBJT.ttf.

URL - https://ik.imagekit.io/demo/tr:l-text,i-overlay%20made%20easy,ff-Lacquer-Regular_nGqtVsBJT.ttf,co-yellow,fs-45,l-end/medium_cafe_B1iTdD0C.jpg

If your custom font file is in a nested folder, then replace the slashes /in the path with @@. For example, a font file available at path /font-folder/font-subfolder/my-custom-font.ttf will be used as follows:

Copy
https://ik.imagekit.io/demo/tr:l-text,i-Hello%20World,ff-font-folder@@font-subfolder@@my-custom-font.ttf,fs-72,co-FFF000,l-end/default-image.jpg

Non-English character support

You can overlay text in any language with custom fonts, for example.

URL - https://ik.imagekit.io/ikmedia/tr:w-600,h-600:l-text,i-इमेजकिट के साथ,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,fs-42,ia-left,pa-10,ly-N100,bg-FFFFFF75,co-145FDD,l-end:l-text,i-दुनिया के कोने-कोने में लोगों तक पहुंचें,pa-5,ly-N35,lx-300,fs-28,ia-right,ff-fonts@@Poppins-Regular_Q15GrYWmL.ttf,bg-FFFFFF75,l-end/girl_in_white.jpg

List of supported text transformations in text layers

ParameterDescription
wThe 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. The height of the text box is calculated automatically based on the total number of lines. It can also accept arithmetic expressions such as bw_mul_0.2, or bh_div_2. Learn more about arithmetic expressions here.
fsIt is used to specify the font size. It can also accept arithmetic expressions such as bw_mul_0.2, or bh_div_20. Learn more about arithmetic expressions here.
ffIt is used to specify the font of the overlaid text on the image. You can choose any font from this list or use a custom font.
coIt is used to specify the color and transparency of the overlaid text on the image. It accepts RGB Hex Codes (e.g. FF0000), or RGBA Codes (e.g. FFAABB50), or color names (e.g. red). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which indicate the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
iaInner alignment. Accepts left, right, and center. The default value is center.
paIt is used to specify the padding around the overlaid text on the image. Supports any positive integer or a set of positive integers separated by underscores. The set of integers follows CSS shorthand order for determining the padding along each side of the overlay. e.g. 10, 10_20, 10_20_30 or 10_20_30_40. It can also accept arithmetic expressions such as bw_mod_5, or bw_div_20. Learn more about arithmetic expressions here.
alIt is used to specify the transparency level of the overlaid text layer. Supports integers from 1 to 9.
tgTypography. Supports bold b, italics i, and bold with italics b_i.
bgIt is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50), or a color name (e.g. red). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which indicate the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.
rtIt is used to specify the degree by which the overlay text must be rotated. It accepts any number e.g. 45, or 180 for a clockwise rotation, or any number preceded with N e.g. N45, or N180 for counter-clockwise rotation.
lhIt is used to specify the line height(spacing) of the text. It will come into effect only if the text wraps over multiple lines. Accepts integer values representing line height in points. It can also accept arithmetic expressions such as bw_mul_0.2, or bh_div_20. Learn more about arithmetic expressions here.

Add solid color blocks over image

You can add a solid color block over a base image using the following example.

Syntax for solid color block overlay

Use i-ik_canvas with the bg parameter to add a solid color block overlay on an image.

Copy
https://ik.imagekit.io/demo/base-image.jpg?tr=l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end

For example, let's add a solid red color box on an image.

URL - https://ik.imagekit.io/demo/tr:l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/medium_cafe_B1iTdD0C.jpg

You can also control the position of the solid color overlay using lx and ly parameters. Learn more about positional parameters.

Apply transformation on solid color overlay

The following transformation parameters are supported on the solid color block overlay inside a layer.

ParameterDescription
wWidth of solid color block. It can also accept arithmetic expressions such as bw_div_2, or bw_mul_0.8. Learn more about arithmetic expressions here.
hHeight of solid color block. It can also accept arithmetic expressions such as bh_div_2, or bh_mul_0.8. Learn more about arithmetic expressions here.
bgIt is used to specify the color of the block in RGB Hex Code (e.g. FF0000), or an RGBA Code (e.g. FFAABB50), or a color name (e.g. red). If you specify an 8-character background, the last two characters must be a number between 00 and 99, which indicates the opacity level of the background. 00 represents an opacity level of 0.00, 01 represents an opacity level of 0.01, and so on.
alIt is used to specify the transparency level of the overlaid solid color layer. Supports integers from 1 to 9.
rIt is used to control the radius of the corner. To get a circle or oval shape, set the value to max.
e-gradientIt is used to add a linear gradient overlay over an input image. The direction, from color, to color, and the stop point of the gradient can be varied using the following parameters - ld, from, to and sp. e.g. e-gradient-<linear-direction>_<from-color>_<to-color>_<stop-point> (or simply e-gradient to let the gradient take on default values). Learn more about the gradient effect and its parameters here.

If both bg and al are set in a single transformation and bg has an alpha component, then that value is used to set solid color background transparency. Otherwise, al value is used. If bg is set to a standard color name (e.g. blue), then the al value is ignored.

Supported text font list

ImageKit.io currently supports the following fonts out of the box.

FontSupport for BoldSupport for Italics
AbrilFatFaceNoNo
AmaranthYesYes
ArvoYesYes
AudiowideNoNo
ChivoYesYes
Crimson TextYesYes
exoYesYes
Fredoka OneNoNo
Gravitas OneNoNo
KanitYesYes
LatoYesYes
LobsterNoNo
LoraYesYes
MonotonNoNo
MontserratYesYes
PT MonoNoNo
PT_SerifYesYes
Open SansYesYes
RobotoYesYes
Old StandardYesYes
UbuntuYesYes
VollkornYesYes

Besides this you can use any custom font by uploading the font file in your media library and passing its path in the ff parameter in a text layer. See custom font example here.