ImageKit.io JavaScript SDK

Lightweight JavaScript SDK for generating optimized URLs for images and videos, and for handling file uploads via ImageKit.

Table of Contents

• Installation
• Initialization
• URL Generation
  • Basic URL Generation
  • Advanced URL Generation Examples
  • Supported Transformations
  • Handling Unsupported Transformations
• File Upload
  • Basic Upload Example
  • Promise-based Upload Example
• Test Examples
• Changelog

Installation

Using npm

Install the SDK via npm:

npm install imagekit-javascript --save
# or
yarn add imagekit-javascript

Then import ImageKit:

import ImageKit from "imagekit-javascript";
// or with CommonJS:
const ImageKit = require("imagekit-javascript");

Using CDN

You can also use the global CDN:

Download a specific version:

https://unpkg.com/imagekit-javascript@1.3.0/dist/imagekit.min.js

Or for the latest version, remove the version number:

https://unpkg.com/imagekit-javascript/dist/imagekit.min.js

And include it in your HTML:

<script type="text/javascript" src="https://unpkg.com/imagekit-javascript/dist/imagekit.min.js"></script>

Initialization

Initialize the SDK by specifying your URL endpoint. You can obtain your URL endpoint from https://imagekit.io/dashboard/url-endpoints and your public API key from https://imagekit.io/dashboard/developer/api-keys. For URL generation:

var imagekit = new ImageKit({
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id"
});

For client-side file uploads, include your public key:

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

Note: Never include your private key in client-side code. If provided, the SDK throws an error.

URL Generation

The SDK’s .url() method enables you to generate optimized image and video URLs with a variety of transformations.

Basic URL Generation

1. Using an Image Path with a URL Endpoint

   var imageURL = imagekit.url({
       path: "/default-image.jpg",
       urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
       transformation: [{
           "height": "300",
           "width": "400"
       }]
   });

   Result Example:

   https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg

2. Using a Full Image URL (src)

   var imageURL = imagekit.url({
       src: "https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg",
       transformation: [{
           "height": "300",
           "width": "400"
       }]
   });

   Result Example:

   https://ik.imagekit.io/your_imagekit_id/endpoint/default-image.jpg?tr=h-300%2Cw-400

Advanced URL Generation Examples

Chained Transformations

Apply multiple transformations by passing an array:

var imageURL = imagekit.url({
    path: "/default-image.jpg",
    transformation: [{
        "height": "300",
        "width": "400"
    }, {
        "rotation": 90
    }],
    transformationPosition: "query" // Use query parameter for transformations
});

Result Example:

https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-300%2Cw-400%3Art-90

Overlays and Effects

Text Overlay Example:

var imageURL = imagekit.url({
    src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg",
    transformation: [{
        "width": 400,
        "height": 300,
        "raw": "l-text,i-Imagekit,fs-50,l-end"
    }]
});

Image Overlay Example:

var imageURL = imagekit.url({
    src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg",
    transformation: [{
        "width": 400,
        "height": 300,
        "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end"
    }]
});

AI and Advanced Transformations

Background Removal:

var imageURL = imagekit.url({
  path: "/sample-image.jpg",
  transformation: [{
    aiRemoveBackground: true
  }]
});

Upscaling:

var upscaledURL = imagekit.url({
  path: "/sample-image.jpg",
  transformation: [{
    aiUpscale: true
  }]
});

Drop Shadow:

var dropShadowURL = imagekit.url({
  path: "/sample-image.jpg",
  transformation: [{
    aiDropShadow: "az-45"
  }]
});

Arithmetic Expressions in Transformations

var imageURL = imagekit.url({
    src: "https://ik.imagekit.io/your_imagekit_id/default-image.jpg",
    transformation: [{
        "width": "iw_div_4",
        "height": "ih_div_2",
        "border": "cw_mul_0.05_yellow"
    }]
});

Supported Transformations

The SDK gives a name to each transformation parameter e.g. height for h and width for w parameter. It makes your code more readable. If the property does not match any of the following supported options, it is added as it is.

If you want to generate transformations in your application and add them to the URL as it is, use the raw parameter.

Check ImageKit transformation documentation for more details.

Handling Unsupported Transformations

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:

var imageURL = imagekit.url({
    path: "/test_path.jpg",
    transformation: [{
        "newparam": "cool"
    }]
});
// Generated URL: https://ik.imagekit.io/test_url_endpoint/tr:newparam-cool/test_path.jpg

File Upload

The SDK offers a simple interface via the .upload() method to upload files to the ImageKit Media Library. This method requires the following:

• file (mandatory)
• fileName (mandatory)
• Security parameters: signature, token, and expire

Before invoking the upload, generate the necessary security parameters as per the ImageKit Upload API documentation.

Basic Upload Example

Below is an HTML form example that uses a callback for handling the upload response:

<form action="#" onsubmit="upload(); return false;">
    <input type="file" id="file1" />
    <input type="submit" />
</form>
<script src="../dist/imagekit.js"></script>
<script>
    var imagekit = new ImageKit({
        publicKey: "your_public_api_key",
        urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
    });
    
    function upload() {
        var file = document.getElementById("file1");
        imagekit.upload({
            file: file.files[0],
            fileName: "abc1.jpg",
            token: 'generated_token',
            signature: 'generated_signature',
            expire: 'generated_expire'
        }, function(err, result) {
            if(err){
                console.error(err);
            } else {
                console.log(result);
            }
        });
    }
</script>

Promise-based Upload Example

You can also use promises for a cleaner asynchronous approach:

imagekit.upload({
    file: file.files[0],
    fileName: "abc1.jpg",
    token: 'generated_token',
    signature: 'generated_signature',
    expire: 'generated_expire'
}).then(result => {
    console.log(result);
}).catch(error => {
    console.error(error);
});

Test Examples

For a quick demonstration of the SDK features, refer to our test examples:

• URL Generation examples can be found in test/url-generation.js
• File Upload examples can be found in test/upload.js

Changelog

For a detailed history of changes, please refer to CHANGELOG.md.