ImageKit.io Docs
PricingService statusDashboardWe are hiring 🤓
Search…
What is ImageKit.io?
📌Getting Started
Getting started
How to use ImageKit.io?
🔧External storage
Integration overview
How it works?
Configure origin
URL-endpoints
ImageKit.io storage
Media Library
Limits and troubleshooting
Limits
Error troubleshooting
Testing and Infrastructure Setup
Testing on multiple environments
Using on multiple websites
Using with your CDN
Using with a custom domain name
✨Features
Image Transformations
Resize, crop and other common transformations
Overlay
Image enhancement & color manipulation
Chained transformations
Supported text font list
Image Optimization
Video Transformation (Beta release)
Video Optimization (Beta release)
Named Transformations
Network-based image optimization
Client hints
Caches
Cache purging
Security
SEO-friendly image URL
Default Images
Progressive JPEGs
Non-image file compression
Performance monitoring
User access management
Multi factor authentication
Billing alerts
Single sign-on
URL-rewriters
Platform guides
Magento
WordPress
Shopify
Sample projects
Upload widget
Media library widget
📙API Reference
API Introduction
Upload file API
Media API
Metadata API
Custom metadata fields API
EXTENSIONS
Extensions reference
Powered By GitBook
Resize, crop and other common transformations
A comprehensive guide that covers all the commonly used image transformations that you will need for your web applications.

Basic image resizing

Width - (w)

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.
You can also specify the auto_ _value for this parameter (w-auto). Doing so will instruct ImageKit to read the width value from the Width Client Hint request header. Learn more about client hints here.

Height - (h)

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.

Aspect ratio - (ar)

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 ar-<width>-<height>
If you specify both height(h) and width(w) in the URL along with aspect ratio(ar), then the aspect ratio is ignored.

Crop, Crop Modes and Focus

If only, one of the height(h) or width(w) dimensions is specified, then ImageKit.io adjusts the other dimension accordingly to preserve aspect ratio and no cropping takes place.
But when you specify both height(h) and width(w) dimensions, you need to choose the right cropping strategy based on your website layout and desired output image.
Tip for choosing the right cropping strategy
😎
**** ****When choosing among different strategies for cropping, think in terms of your website layout and desired output image.
  • If you want to preserve the whole image content (no cropping) and need the exact same dimensions (height and width) in the output image as requested, choose either of the pad resize crop or forced crop strategy.
  • If you want to preserve the whole image content (no cropping), but it is okay if one or both the dimensions (height or width) in the output image are adjusted to preserve the aspect ratio. Then choose either of the max-size cropping or min-size cropping strategy.
  • 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.

Pad resize crop strategy - (cm-pad_resize)

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.
Original
cm-pad_resize
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
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.
300x200 image
For sake of clarity, we have made the padding background slightly grey in color (#F3F3F3) using the background parameter (bg) in the URL.

Example - All padding on one side

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.
Padding to the right
Padding to the bottom
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).
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-100,h-200,cm-pad_resize,bg-F3F3F3,fo-top​
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).

Forced crop strategy - (c-force)

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.
Original
c-force
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,c-force​
300x200 image
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.

Max-size cropping strategy - (c-at_max)

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.
Original
c-at_max
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,c-at_max​
148x200 image
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.

Min-size cropping strategy - (c-at_least)

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.
Original
c-at_least
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,c-at_least​
300x405 image
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.

Maintain ratio crop strategy - (c-maintain_ratio)

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.
By default ImageKit.io extract the image from the center but you can change this using focus parameter.
Original
c-maintain_ratio (center crop)
c-maintain_ratio with fo-custom
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200,c-maintain_ratio or https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-200​
300x200 cropped 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​

Extract crop strategy - (cm-extract)

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.
By default, ImageKit.io extracts the image from the center but you can change this using the focus parameter.

Examples - Center and relative focus

Original
cm-extract (default center extract)
Relative focus
URL - https://ik.imagekit.io/demo/img/plant.jpeg​
Original 640x865 image
URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-200,h-200,cm-extract​
200x200 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 - center, top, left, bottom, right, top_left, top_right, bottom_left and bottom_right.
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.
This is the extract done with focus on bottom right of the original image.

Examples - Focus using cropped image coordinates

Focus using X, Y coordinates
Focus using center coordinates (XC, YC)
In the coordinate method of focus, we use the parameters x and 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
The extract is made starting from (100,300) point on the original image
In the center coordinate method of focus, we use the parameters xc and yc to determine the position of the center of the image which would be extracted.
Example URL - https://ik.imagekit.io/demo/img/plant.jpeg?tr=w-300,h-300,cm-extract,xc-300,yc-500​
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.

Example - Focus using custom coordinates

Instead of specifying the x, y, xc or 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.
Original
Focus using custom coordinates
URL - https://ik.imagekit.io/demo/img/bike-image.jpeg​
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.

Unexpected behavior with auto rotation

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 x and y to accommodate for the oriented image.

Pad extract crop strategy - (cm-pad_extract)

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.
Original
cm-pad_extract
URL - https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg​
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.

Focus - (fo)

This parameter can be used along with pad resize, maintain ratio or extract crop to change the behaviour of padding or cropping. Learn more from the different examples shown in respective sections.
This parameter can have following values depending upon where it is being used:
  1. 1.
    left, right, top, bottom can be to control the position of padding when used with pad resize. Learn from example.
  2. 2.
    fo-custom can be used to define a specific focus area when used with maintain ratio and extract crop.
  3. 3.
    center, top, left, bottom, right, top_left, top_right, bottom_left and 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. auto and face. Let's see them in action:

Auto smart cropping - (fo-auto)

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.
Original
Regular cropping
Smart crop (fo-auto)
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.

Face cropping - (fo-face)

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.
Original
Smart crop (fo-face)
URL - https://ik.imagekit.io/demo/img/girl.jpeg​
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.
**Note: **Smart crop may not give accurate results for some images. This is partially a trade off between speed (needed for real-time transformations) and accuracy.

Commonly used transformations

Quality - (q)

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)

Format - (f)

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 auto ,jpg , jpeg , webp, avif and png
Default Value - auto (from dashboard settings)
A few WebP images may not render correctly in Safari v14+ on MacOS v11+ and IOS 14 because of a possible OS-level issue.

Blur - (bl)

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, the larger the radius of Gaussian Blur. Possible values include integers between 1 and 100.

Grayscale - (e-grayscale)

Used to turn an image to a grayscale version.

DPR - (dpr)

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 a high device pixel ratio (DPR > 1), like the iPhone or high-end Android devices.
The dpr parameter 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.
Possible Values- 0.1 to 5 .
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 transformation - (n)

​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: https://ik.imagekit.io/demo/img/tr:n-media_library_thumbnail/default-image.jpg​

Default image - (di)

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​
If the default image is nested inside multiple folders, then you need to specify the entire default image path in this parameter. Replace / with @@ in the default image path. For example, if the default image is accessible on https://ik.imagekit.io/demo/path/to/image.jpg, then the di parameter should be [email protected]@[email protected]@[email protected]@image.jpg.

Progressive image - (pr)

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 true and false . https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,pr-true/medium_cafe_B1iTdD0C.jpg​

Lossless WebP and PNG - (lo)

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. Possible Values- true and false https://ik.imagekit.io/demo/tr:w-500,h-361,lo-true/medium_cafe_B1iTdD0C.jpg​

Trim edges - (t)

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.
Usage - t-true|Number Possible Values include true and integer values between 1 and 99 that specify the threshold level for considering a particular pixel as "background".
Trim true
With trim equal to 5
With trim equal to 15
URL - https://ik.imagekit.io/demo/img/tr:t-true/trim_example_BkgQVu7oX.png​
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 true
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.

Border - (b)

This adds a border to the image. It accepts two parameters - the width of the border and the color of the border.
Usage - b-<border-width>-<hex code>
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.

Color profile - (cp)

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 true.
Default Value- false (from the dashboard)
Possible Values- true and false
cp=false (Default)
cp=true
URL - https://ik.imagekit.io/demo/tr:h-300,w-400,f-jpg,cp-false/medium_cafe_B1iTdD0C.jpg​
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.

Image metadata - (md)

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.
Default Value- false (from the dashboard)
Possible Values- true and false

Rotate - (rt)

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 auto parameter.
Possible Values- 0 , 90 , 180 , 270 , 360 , and auto
Use auto if you want ImageKit.io to automatically rotate image based on EXIF orientation tag in image metadata.

Radius - (r)

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 max
For simpler cases, you can use radius in the same transformation as the height and width parameters. However, if you are using advanced cropping parameters, like crop (c) and crop mode (cm), then you should chain the radius transformation in a step after the resizing transformation.

Background color - (bg)

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 00 and 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

Specifying a background for a PNG image

Original image - (orig)

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.

Downloading file - (ik-attachment)

Set ik-attachment=true query param in the URL to download the file as an attachment rather than viewing it inline in the web browser.
By specifying this parameter in the file URL, ImageKit sets the content-disposition header in the response with the value attachment along with the file name.
✨Features - Previous
Image Transformations
Next
Overlay
Last modified 3mo ago
Copy link
Contents
Basic image resizing
Width - (w)
Height - (h)
Aspect ratio - (ar)
Crop, Crop Modes and Focus
Pad resize crop strategy - (cm-pad_resize)
Forced crop strategy - (c-force)
Max-size cropping strategy - (c-at_max)
Min-size cropping strategy - (c-at_least)
Maintain ratio crop strategy - (c-maintain_ratio)
Extract crop strategy - (cm-extract)
Pad extract crop strategy - (cm-pad_extract)
Focus - (fo)
Commonly used transformations
Quality - (q)
Format - (f)
Blur - (bl)
Grayscale - (e-grayscale)
DPR - (dpr)
Named transformation - (n)
Default image - (di)
Progressive image - (pr)
Lossless WebP and PNG - (lo)
Trim edges - (t)
Border - (b)
Color profile - (cp)
Image metadata - (md)
Rotate - (rt)
Radius - (r)
Background color - (bg)
Original image - (orig)
Downloading file - (ik-attachment)