Used to specify the width of the output image. Accepts integer value greater than 1. If a value between 0 and 1 is specified, it acts as a percentage width. Therefore, 0.1 means 10% of the original width, 0.4 means 40% of the original width, and so on.
Used to specify the height of the output image. Accepts integer value greater than 1. If a value between 0 and 1 is specified, the value acts as a percentage height. Therefore, 0.1 means 10% of the original height, 0.4 means 40% of the original height, and so on.
Used to specify the aspect ratio of the output image or the ratio of width to height of the output image. This parameter must be used along with either the height(h) or width(w) parameter. The format for specifying this transformation is
If you need the exact same dimensions (height and width) in the output image as requested but it's okay to crop the image to preserve the aspect ratio (or extract a region from the original image). Then choose either of the maintain ratio crop or extract crop or pad extract crop strategy. You can combine the extract crop strategy with different focus values to get the desired result.
In the pad resize crop strategy, the output image's dimension (height and width) is the same as requested, no cropping takes place, and the aspect ratio is preserved. This is accomplished by adding padding around the output image to get it to match the exact dimension as requested.
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,cm-pad_resize,bg-F3F3F3 The output image is exactly 300x200. However, to maintain the aspect ratio and prevent cropping a solid colored padding is added around the resized image.
For sake of clarity, we have made the padding background slightly grey in color (#F3F3F3) using the background parameter (
bg) in the URL.
In the examples above, we saw that when the image is padded using the pad resize crop strategy, the padding is equal on both sides of the image. However, there might be cases where we want all the padding to be added on only one side of the image. This can be done using the focus (fo) parameter.
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,cm-pad_resize,bg-F3F3F3,fo-left
We added the
fo-left transformation to our image. Now, all the padding is on the right of the image, while the image itself is on the left (determined by the value of focus(fo) parameter).
We added the
fo-top transformation to our image. Now, all the padding is on the bottom of the image, while the image itself is on the top (determined by the value of focus(fo) parameter).
In a forced crop strategy, the output image's dimension (height and width) is exactly the same as requested, no cropping takes place, but the aspect ratio is not preserved. It forcefully squeezes the original image to get it to fit completely within the output dimensions.
The entire original image is preserved in the output image as well, but the hand and the plant have been squeezed to fit into the output image.
In the max-size crop strategy, whole image content is preserved (no cropping), the aspect ratio is preserved, but one of the dimensions (height or width) is adjusted.
The output image is less than or equal to the dimensions specified in the URL,i.e., at least one dimension will exactly match the output dimension requested, and the other dimension will be equal to or smaller than the corresponding output dimension requested.
The entire image content and the aspect ratio is preserved. The output image dimensions are 148x200. So the height is exactly what is requested, but the width is smaller than what was requested.
This mode is particularly useful if you have a container and you want to ensure that the image will never be larger than that container.
This strategy is similar to the max-size cropping strategy, with the only difference being that unlike the max-size strategy, the image is equal to or larger than the requested dimensions. One of the dimensions will be exactly the same as what is requested, while the other dimension will be equal to or larger than what is requested.
The entire image content and aspect ratio is preserved. The output image dimensions are 300x405. So the width is exactly the same as what was requested, but the height is larger than what was requested.
This is useful for cases where you want to have an image that is always at least as large as the container.
This is the default crop strategy. If nothing is specified in the URL, this strategy gets applied automatically. In this strategy, the output image's dimension (height and width) is the same as requested, and the aspect ratio is preserved. This is accomplished resizing the image to the requested dimension and in the process cropping parts from the original image.
In the above image, the top and the bottom of the image got cropped out. But the aspect ratio has been preserved from the original to the output image i.e. the hand and the plant are not skewed or forcefully resized to fit the output dimensions.
Original image URL - https://ik.imagekit.io/demo/img/bike-image.jpeg
Using c-maintain_ratio with fo-custom - https://ik.imagekit.io/demo/img/bike-image.jpeg?tr=w-500,h-100,fo-custom
In this strategy, the output image's dimension (height and width) is exactly the same as requested, and the aspect ratio is preserved. In this strategy, instead of trying to resize the image as we did in maintain ratio strategy, we extract out a region of the requested dimension from the original image.
The size of the hand and the plant has not changed at all from the original image, which means that no resizing has taken place. Instead, we have been able to extract out a 200x200 area from the original image. This is the regular center extract.
In the relative method, you can use the focus (fo) parameter to specify that the extract should be done from, let's say, the bottom-right of the original image.
Valid relative values for
fo parameters are -
Example URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-300,cm-extract,fo-bottom_right This is the extract done with focus on bottom right of the original image.
In the coordinate method of focus, we use the parameters
y to determine the position of the top-left corner from where the extract would begin.
Example URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-300,cm-extract,x-100,y-300 The extract is made starting from (100,300) point on the original image
In the center coordinate method of focus, we use the parameters
yc to determine the position of the center of the image which would be extracted.
The extract is made centered on (300, 500) point on the original image.
This crop mode is really useful when you want to crop the image on the basis of the focal point of your resultant image.
An important point to note about the center coordinate crop mode is that if either the height or width dimension of the cropped image as per the given center coordinates goes beyond the bounds of the original image, the crop will fail.
So we suggest ensuring that you are using the correct height and width dimensions when cropping images using center coordinates.
Instead of specifying the
xy coordinates to focus on a particular area, you can also specify the focus area in an image while uploading the image or from the media library and then use
fo-custom transformation in the image URL. ImageKit will then utilize the custom crop area specified with the image for all crop operations. This custom focus mode works for both the extract crop and the default maintain ratio crop strategy.
URL - https://ik.imagekit.io/demo/img/bike-image.jpeg?tr=w-500,h-100,fo-custom,cm-extract A 500x100px thumbnail with cm-extract crop strategy and fo-custom.
ImageKit can be configured to auto-rotate images based on the
Orientation value in the image metadata. This could result in unexpected behavior when using,
cm-extract. In that case, you will have to adjust the values of
y to accommodate for the oriented image.
The pad extract crop strategy is an extension of the extract crop strategy. In the extract crop strategy, we were extracting out a smaller area from a larger image. Now, there can be a scenario where the original image is small and we want to extract out a larger area (which is practically not possible without padding). So the pad extract mode adds a solid colored padding around the image to make it match the exact size requested.
This transformation is specified using the value
cm-pad_extract transformation parameter in the URL.
URL - https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=w-700,h-700,cm-pad_extract,bg-F3F3F3 Original image was 600x600 but this image is 700x700 image.
This parameter can have following values depending upon where it is being used:
bottom can be to control the position of padding when used with pad resize. Learn from example.
bottom_right can be used to define relative cropping during extract crop. Learn from examples.
Apart from above,
fo parameter also have two additional options that intelligently detect the most important part of an image to create thumbnails i.e.
face. Let's see them in action:
In this mode, ImageKit automatically determines the most important part of the image and preserves it in the output thumbnail. This is enabled by passing the
fo-auto parameter in the URL transformation parameters.
URL - https://ik.imagekit.io/demo/img/girl.jpeg For example, in the image below, the girl is the main subject of the image and she is slightly towards the left from the center of the image.
URL - https://ik.imagekit.io/demo/img/tr:w-200,h-300/girl.jpeg If we use regular resize and the default crop strategy, we get the following result, where the main subject is off the center. This is definitely not a great thumb image to have.
URL - https://ik.imagekit.io/demo/img/tr:w-200,h-300,fo-auto/girl.jpeg With smart crop auto mode, this is the how the final result looks like. The main subject is right in the center of the final thumbnail.
In face crop, the crop works more like the extract crop strategy, but instead of focusing on the center of the image, it finds out the face (or multiple faces) in the image and focuses around that. This gives you perfect thumbnails with just the subject's face that make up for good profile pictures.
This mode is enabled using 'fo-face' parameter in the URL transformation parameters.
URL - https://ik.imagekit.io/demo/img/tr:w-150,h-150,fo-face/girl.jpeg Quite distinctly from the auto smart crop, this thumbnail is focussed just around the face.
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.
Default Value -
80 (can be managed from image settings in dashboard)
Used to specify the format of the output image. If no output image format is specified then based on your image settings in the dashboard, ImageKit.io automatically picks the best format for that image request.
Possible values include
Default Value -
auto (from dashboard settings)
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. Higher the value, larger the radius of Gaussian Blur. Possible values include integers between
Used to turn an image to a grayscale version.
Used to specify the device pixel ratio that is used to calculate the dimensions of the output image. Extremely helpful when creating image transformations for devices with high device pixel ratio (DPR > 1), like the iPhone or high-end Android devices.
dprparameter can only be used when either the height or width of the desired output 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 DPR is not considered and the height or width used in the URL is used.
Alternatively, you can specify the
auto value for this parameter (dpr-auto). Doing so will instruct ImageKit to read the dpr value from the DPR Client Hint request header. Learn more about client hints here.
Named Transformations are an alias for the entire transformation string.
For example, we can create a named transformation -
thumbnail for a transformation string -
tr:w-100,h-100,c-at_max,fo-auto and is used like:
When an image that is requested using Imagekit.io does not exist, a 404 error is displayed. In certain scenarios, you would want a default image to be delivered instead of the 404 error message.
Imagekit.io provides an alternative to achieve this without having to make changes at the application level using this parameter. The image specified in this parameter should be accessible using the default endpoint of your ImageKit.io account. https://ik.imagekit.io/demo/tr:di-medium_cafe_B1iTdD0C.jpg/non_existent_image.jpg
Used to specify whether the output JPEG image must be rendered progressively. In progressive loading, the output image renders as a low quality pixelated full image which over time keeps on adding more pixels and information to the image. This helps you maintain a fast perceived load time.
Possible values include
Used to specify whether the output image (if in JPEG or PNG) must be compressed losslessly. In lossless compression, the output file size is larger than the regular lossy compression. However, the perceived image quality can be higher in certain cases, especially for computer-generated graphics. Using lossless compression for photographs is not recommended.
Useful with images that have a solid or nearly solid background with the object in the center. This parameter trims the background from the image, leaving only the central object in the output image.
Possible Values include
true and integer values between
99 that specify the threshold level for considering a particular pixel as "background".
URL - https://ik.imagekit.io/demo/img/tr:t-5/trim_example_BkgQVu7oX.png
Here some trimming does take place (you can notice that the grey circle in the background is getting cut off), but it is not as much as what happened when the value of trim was set to
URL - https://ik.imagekit.io/demo/img/tr:t-15/trim_example_BkgQVu7oX.png
Here the amount of trimming is higher than what happened with trim set to
true. This is because with a higher value specified for trim, more and more pixels are considered as similar and redundant and hence get removed.
This adds a border to the image. It accepts two parameters - the width of the border and the color of the border.
The width is specified as a number which is equivalent to the border width in pixels. The color code is specified as a 6-character hex code RRGGBB.
It is used to specify whether the output image should contain the color profile that is initially available with the original image. It is recommended to remove the color profile before serving the images on web and apps. However, if you feel that the output image looks faded or washed out after using ImageKit.io, and want to preserve the colors of your original image, you should set this parameter to
false (from the dashboard)
URL - https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,cp-true/medium_cafe_B1iTdD0C.jpg You might not observe any change in this particular image. It depends on if the original image has any specific color profile or not.
It is used to specify whether the output image should contain all the metadata that is initially available with the original image. Image metadata is not relevant for rendering on the web and apps. It is, thus, recommended to not use it while delivering images. The only situation to enable the metadata option is when you want additional data like camera information, lens information, and other image profiles attached to your original image.
false (from the dashboard)
It is used to specify the degree by which the output image must be rotated or specifies the use of EXIF Orientation Tag for the rotation of image using the
360 , and
It is used to specify the radius that must be used to obtain a rounded output image. To obtain a perfectly rounded image, set the value to
max . This parameter is applied after resizing the original image, if defined.
Possible Values - Positive Integer and
URL - https://ik.imagekit.io/demo/tr:r-max/medium_cafe_B1iTdD0C.jpg This is good for creating profile pictures.
It is used to specify the background color in RGB Hex Code (e.g. FF0000) or an RGBA Code (e.g. FFAABB50) that must be used for the image. If you specify an 8 character background, the last two characters must be a number between
99 , which is used to indicate the opacity level of the background.
00 represents an opacity level of 0.00,
01 represents opacity level 0.01, and so on.
Default Value - Black 00000
Possible Values - Valid RGB Hex Code
By default, any image that is delivered via ImageKit.io always gets optimized in some way or the other. While this automatic optimization is great for web and apps, there might be certain cases where you want to get the original image as is. You can do so by using the parameter
orig and set the value to
true . If there are any other transformation parameters specified along with
orig-true , then those get ignored.