JavaScript ImageKit SDK

The ImageKit JavaScript SDK provides easy-to-use utility functions for generating optimized image and video URLs, applying a wide range of transformations (resize, crop, overlays, effects, and even AI-powered enhancements), and uploading files. It is designed specifically for browser-based environments. If you are looking to use ImageKit on Node.js, please refer to the ImageKit Node.js SDK.

The SDK is lightweight, does not require any dependencies, and has first-class TypeScript support. You can view the source code on GitHub.

Install the SDK via npm or yarn:

npm install @imagekit/javascript
# or
yarn add @imagekit/javascript

You can also include the SDK directly in your HTML using a script tag. It is recommended to load a specific version to avoid unexpected breaking changes:

<script src="https://unpkg.com/@imagekit/javascript@5.0.0/dist/imagekit.min.js"></script>

For environments with module bundlers (e.g., webpack, Rollup) or ES modules, simply import the functions:

import { buildSrc, buildTransformationString, upload } from '@imagekit/javascript';

The JavaScript SDK exports the following:

• buildSrc - To generate complete URLs for images and videos with transformations.
• buildTransformationString - To generate transformation strings so that you can use them in your own URL generation logic.
• upload - To upload files to ImageKit.

• ImageKitInvalidRequestError - For invalid requests.
• ImageKitAbortError - For aborted uploads.
• ImageKitUploadNetworkError - For network errors during upload.
• ImageKitServerError - For server-side errors.

The SDK provides TypeScript type definitions for all the parameters and options used in the SDK. This includes types for SrcOptions, UploadOptions, UploadResponse, and Transformation.

The SDK provides two helper functions:

• buildSrc - To generate complete URLs for images and videos with transformations.
• buildTransformationString - To generate transformation strings so that you can use them in your own URL generation logic.

The buildSrc function accepts an options object with the following parameters:

The buildTransformationString accepts an array of transformation objects and returns the transformation string.

import { buildTransformationString } from '@imagekit/javascript';
const transformationString = buildTransformationString([
  { width: 300, height: 300 },
  { overlay: { type: "text", text: "Hello World" } }
]);
console.log(transformationString);
// Expected output: "w-300,h-300:l-text,i-Hello%20World,l-end"

ImageKit allows you to resize images and videos on-the-fly using the width and height parameters.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ width: 300, height: 300 }]
});

You can chain multiple transformations together by passing an array of transformation objects. Each object can specify different properties, such as width, height, cropping, overlays, and effects. See chained transformations for more details.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [
    { width: 400, height: 300 },
    { rotation: 90 }
  ]
});

You can add overlays to images and videos. The overlay can be a text, image, video, or subtitle.

Besides the overlay type, you can also specify the position, size, and other properties of the overlay. Check the overlay options for more details.

// Image overlay example:
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "image", 
        input: "logo.png"
      } 
    }
  ]
});

You can further transform the overlay image independently of the base image by adding additional transformation parameters. For example, to resize the overlay image:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "image", 
        input: "logo.png", 
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]
});

Image overlays support a wide range of transformations. Check reference for a complete list of transformations supported on image overlays.

You can add a solid color overlay to images and videos.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "solidColor", 
        color: "FF0000" // Required
      } 
    }
  ]
});

You can also specify the width, height, and other properties of the solid color overlay. For example:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "solidColor", 
        color: "FF0000", // Required
        transformation: [
          { width: 100, height: 100 }
        ]
      } 
    }
  ]
});

For more options related to styling the solid color overlay, check the solid color overlay transformations section.

You can add text overlays to images and videos.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { type: "text", text: "Hello, ImageKit!" } 
    }
  ]
});

You can also specify the font size, color, and other properties of the text overlay. For example:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.jpg",
  transformation: [
    { 
      overlay: { 
        type: "text", 
        text: "Hello, ImageKit!", 
        transformation: [
          { fontSize: 20, fontColor: "FF0000" }
        ]
      } 
    }
  ]
});

Check the text overlay transformations section for more options related to styling the text.

You can add video overlays on videos only.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4"
      } 
    }
  ]
});

Additionally, you can specify the start and end time for the overlay video. For example:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4", 
        timing: { start: 5, duration: 10 } // Overlay appears at 5 seconds and lasts for 10 seconds
      } 
    }
  ]
});

You can also independently transform the overlay video. For example, to resize the overlay video:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { 
        type: "video", 
        input: "video.mp4", 
        transformation: [
          { width: 100, height: 100 } // Resize overlay video independently
        ] 
      } 
    }
  ]
});

All supported video transformations can also be applied to overlay videos.

If you're overlaying an image on a base video, refer to this list for all the transformations supported on image overlays.

You can add subtitle overlays on videos.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/background.mp4",
  transformation: [
    { 
      overlay: { type: "subtitle", input: "subtitle.srt" } 
    }
  ]
});

The subtitle overlay can be styled with various properties such as font size, color, and outline. See the Subtitle Overlay Transformations section for all styling options.

You can use the aiRemoveBackground transformation to remove the background from images. This is particularly useful for e-commerce applications.

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiRemoveBackground: true }]
});

ImageKit supports multiple AI-powered transformations, like upscaling, generative fill, and more. You can use these transformations to enhance your images without needing to manually edit them. Check the AI Transformations section for more details.

More examples:

// Drop shadow using AI
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiDropShadow: true }]
});

// Upscale a small image using AI
buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ aiUpscale: true }]
});

You can use arithmetic expressions to dynamically compute transformation values. For example, to set the width to half of the original image width:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [{ width: "iw_div_2" }]
});

Check out the Arithmetic Expressions reference for more examples and details.

The upload() function enables you to upload files to ImageKit using upload V1 API. It accepts an options object and returns a promise that resolves with an upload response. The SDK JSON stringifies certain parameters before sending them to the server as expected by the API. If the SDK does not support a parameter, it is added as-is in the request. Check the API documentation for more details.

The upload() function accepts a JSON object with the following parameters:

The .upload function requires you to send token, signature, expire and publicKey parameters. Check the signature generation section for more details on how to generate these values.

import { upload, ImageKitInvalidRequestError, ImageKitAbortError, ImageKitUploadNetworkError, ImageKitServerError } from '@imagekit/javascript';

const fileInput = document.getElementById('fileInput');
const abortController = new AbortController(); // You can abort the upload using abortController.abort();

// Get required token, signature, and expire values from your server. Check the signature generation below for more details.

fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const uploadOptions = {
    file,
    fileName: file.name,
    token: "your_upload_token", // Check signature generation section for more details
    signature: "your_generated_signature",
    expire: Math.floor(Date.now() / 1000) + 3600,
    publicKey: "your_public_key",
    onProgress: (event) => {
      console.log(`Progress: ${event.loaded}/${event.total}`);
    },
    abortSignal: abortController.signal
  };
  
  try {
    const response = await upload(uploadOptions);
    console.log("Upload successful:", response);
  } catch (error) {
    if (error instanceof ImageKitAbortError) {
      // You aborted the upload
      console.error("Upload aborted:", error.reason);
    } else if (error instanceof ImageKitInvalidRequestError) {
      // You made an invalid request
      console.error("Invalid request:", error.message);
    } else if(error instanceof ImageKitUploadNetworkError) {
      // Random network error on client side
      console.error("Network error:", error.message);
    } else if (error instanceof ImageKitServerError) {
      // Error on ImageKit server side (5xx). Usually rare and temporary.
      console.error("Server error:", error.message);
    } else {
      // Any other error. You love JavaScript, right?
      console.error("Upload error:", error);
    }
  }
});

The .upload function requires you to send token, signature, and expire parameters. These are used to authenticate the upload request. These values should be generated in your secure backend server and passed to the client. The SDK does not generate these values for you. However, all ImageKit SDKs (Java, PHP, Node.js, Python, Ruby, etc.) provide methods to generate these values. You can use any of these SDKs to generate the signature and token.

Check the upload API documentation for more details on how to generate the signature and token.

Sample code to generate the signature and token using Node.js SDK:

var ImageKit = require("imagekit"); // Node.js SDK

var imagekit = new ImageKit({
    publicKey : "your_public_api_key",
    privateKey : "your_private_api_key",
    urlEndpoint : "https://ik.imagekit.io/your_imagekit_id/"
});

var { token, expire, signature } = imagekit.getAuthenticationParameters();
console.log({token, expire, signature});

The SDK gives a name to each transformation parameter (e.g. height maps to h, width maps to w). If the property does not match any of the following supported options, it is added as is in the URL.

If you want to generate transformations without any modifications, use the raw parameter. For example, the SDK doesn't provide a nice way to write conditional transformations, so you can use the raw parameter to add them as is.

Check transformation documentation for a complete reference on all transformations supported by ImageKit.

If you specify a transformation parameter that is not explicitly supported by the SDK, it is added “as-is” in the generated URL. This provides flexibility for using new or custom transformations without waiting for an SDK update.

For example:

buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/photo.jpg",
  transformation: [
    { unsupportedTransformation: "value" }
  ]
});
// Output: https://ik.imagekit.io/your_imagekit_id/photo.jpg?tr=unsupportedTransformation-value

This SDK provides overlay as a transformation parameter. The overlay can be a text, image, video, subtitle, or solid color.

Overlays in ImageKit are applied using layers, allowing you to stack multiple overlays on top of each other. Each overlay can be styled and positioned independently. For more details, refer to the layer documentation.

The SDK automatically generates the correct layer syntax for image, video, text, subtitle, and solid color overlays. You can also specify the overlay position, size, and other properties.

The table below outlines the available overlay configuration options:

Overlay encoding options define how the overlay input is converted for URL construction. When set to auto, the SDK automatically determines whether to use plain text or Base64 encoding based on the input content.

For text overlays:

• If auto is used, the SDK checks the text overlay input: if it is URL-safe, it uses the format i-{input} (plain text); otherwise, it applies Base64 encoding with the format ie-{base64_encoded_input}.
• You can force a specific method by setting encoding to plain (always use i-{input}) or base64 (always use ie-{base64}).
• Note: In all cases, the text is percent-encoded to ensure URL safety.

For image, video, and subtitle overlays:

• The input path is processed by removing any leading/trailing slashes and replacing inner slashes with @@ when plain is used.
• Similarly, if auto is used, the SDK determines whether to apply plain text or Base64 encoding based on the characters present.
• For explicit behavior, use plain or base64 to enforce the desired encoding.

Use auto for most cases to let the SDK optimize encoding, and use plain or base64 when a specific encoding method is required.