imagekitio-react v4.0.0

ImageKit.io React SDK

ImageKit React SDK allows you to resize, optimize, deliver, and upload images and videos in your React application.

ImageKit is a complete media storage, optimization, and transformation solution that comes with an image and video CDN. It can be integrated with your existing infrastructure - storage like AWS S3, web servers, your CDN, and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.

Breaking changes

Upgrading from 3.x to 4.x version

1. Overlay syntax update

• In version 4.0.0, we've removed the old overlay syntax parameters for transformations, such as oi, ot, obg, and more. These parameters are deprecated and will start returning errors when used in URLs. Please migrate to the new layers syntax that supports overlay nesting, provides better positional control, and allows more transformations at the layer level. You can start with examples to learn quickly.
• You can migrate to the new layers syntax using the raw transformation parameter.

2. IKContext props update

• IKContext has been updated to only include urlEndpoint, publicKey, authenticator, and transformationPosition props, removing others that were more specific to image, video, and upload, and not typically set globally.

Upgrading from 2.x to 3.x version

3.x version has breaking changes as listed below.

• In version 3.0.0, we have deprecated the use of the authenticationEndpoint parameter. Instead, the SDK now introduces a new parameter named authenticator. This parameter expects an asynchronous function that resolves with an object containing the necessary security parameters i.e signature, token, and expire.
• Now ref needs to be passed instead of inputRef in the IKUpload component

An example implementation for authenticator using Fetch API.

 const authenticator = async () => {
    try {

        // You can also pass headers and validate the request source in the backend, or you can use headers for any other use case.
        const headers = {
          'CustomHeader': 'CustomValue'
        };

        const response = await fetch('server_endpoint', {
            headers
        });

        if (!response.ok) {
            const errorText = await response.text();
            throw new Error(`Request failed with status ${response.status}: ${errorText}`);
        }

        const data = await response.json();
        const { signature, expire, token } = data;
        return { signature, expire, token };
    } catch (error) {
        throw new Error(`Authentication request failed: ${error.message}`);
    }
};

Note: Avoid generating security parameters on the client side. Always send a request to your backend to retrieve security parameters, as the generation of these parameters necessitates the use of your Imagekit privateKey, which must not be included in client-side code.

Installation

npm install --save imagekitio-react

or

yarn add imagekitio-react

Usage

Initialization

Import components in your code:

import { IKImage, IKVideo, IKContext, IKUpload } from 'imagekitio-react'

Quick examples

<IKContext urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
  // Render an image using a relative path - https://ik.imagekit.io/your_imagekit_id/default-image.jpg
  <IKImage path="/default-image.jpg" />

  // Overriding urlEndpoint defined in parent IkContext - https://www.custom-domain.com/default-image.jpg
  <IKImage urlEndpoint="https://www.custom-domain.com" path="/default-image.jpg" />

  // Render an image using an absolute URL - https://www1.custom-domain.com/default-image.jpg?tr=w-100
  <IKImage src="https://www1.custom-domain.com/default-image.jpg?tr=w-100" />

  // Height and width manipulation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200/default-image.jpg
  <IKImage path="/default-image.jpg" transformation={[{
    "height": "200",
    "width": "200"
  }]} />

  // Chained transformation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200:rt-90/default-image.jpg
  <IKImage path="/default-image.jpg" transformation={[{
    "height": "200",
    "width": "200",
  },
  {
    "rotation": "90"
  }]} />

  // Lazy loading image
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      "height": "200",
      "width": "200"
    }]}
    loading="lazy"
  />

  /*
     Low-quality image placeholder
     Will first load https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200:q-20,bl-6/default-image.jpg, while the original image, i.e., https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200/default-image.jpg is being loaded in the background.
  */
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      "height": "200",
      "width": "200"
    }]}
    lqip={{ active: true }}
  />

  // Low-quality image placeholder with custom quality and blur values
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      "height": "200",
      "width": "200"
    }]}
    lqip={{ active: true, quality: 20, blur: 10 }}
  />

  // Low-quality image placeholder and lazy loading of original image in the background
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      "height": "200",
      "width": "200"
    }]}
    loading="lazy"
    lqip={{ active: true }}
  />

  // Video element with basic transformation, reduced quality by 50% using q:50
  <IKVideo
    path={'/default-video.mp4'}
    transformation={[{ height: 200, width: 200, q: 50 }]}
    controls={true}
  />
</IKContext>

<IKContext publicKey="your_public_api_key">
  // Simple file upload and response handling
  <IKUpload
    onError={onError}
    onSuccess={onSuccess}
  />

  // Passing different upload API options
  <IKUpload
    fileName="file-name.jpg"
    tags={["sample-tag1", "sample-tag2"]}
    customCoordinates={"10,10,10,10"}
    isPrivateFile={false}
    useUniqueFileName={true}
    responseFields={["tags"]}
    folder={"/sample-folder"}
    ref={uploadRef}
    onError={onError} onSuccess={onSuccess}
    transformation={{
      pre: 'l-text,i-Imagekit,fs-50,l-end', 
      post: [
        {
          'type': 'transformation', 
          'value': 'w-100'
        }
      ]
    }}
  />
</IKContext>

Demo application

• The official step-by-step React quick start guide - https://docs.imagekit.io/getting-started/quickstart-guides/react
• The official step-by-step React Native quick start guide - https://docs.imagekit.io/getting-started/quickstart-guides/react-native

Components

The library includes 5 Components:

• IKContext for defining options like urlEndpoint, publicKey or authenticator to all children elements. This component does not render anything.
• IKImage for image resizing. This renders a <img> tag.
• IKVideo for video resizing. This renders a <video> tag.
• IKUploadfor client-side file uploading. This renders a <input type="file"> tag.
• IKCore for Core SDK, This exposes methods from ImageKit javascript SDK like url and upload.

IKContext

To use this SDK, you need to provide it with a few configuration parameters. You can use a parent IKContext component to define common options for all children IKImage, IKVideo or IKupload components. For example:

<IKContext
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id"  // Required. Default URL-endpoint is https://ik.imagekit.io/your_imagekit_id
  publicKey="your_public_api_key" // optional
  transformationPosition="path" // optional
  authenticator={()=>Promise} // optional
  <IKImage path="/default-image.jpg" />
</IKContext>

will render:

<img alt="" src="https://ik.imagekit.io/your_imagekit_id/default-image.jpg">

• urlEndpoint is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard/url-endpoints.
• publicKey and authenticator parameters are required if you want to use the SDK for client-side file upload. You can get these parameters from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard/developer/api-keys.
• transformationPosition is optional. The default value for this parameter is path. Acceptable values are path & query

Note: Do not include your private key in any client-side code.

Image resizing

The IKImage component renders an img tag. It is used for rendering and manipulating images in real time. IKImage component accepts the following props:

Basic resizing examples

<IKContext urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
  // Image from related file path with no transformations - https://ik.imagekit.io/your_imagekit_id/default-image.jpg
  <IKImage
    path="/default-image.jpg"
  />

  // Image resizing - https://ik.imagekit.io/your_imagekit_id/tr:w-h-300,w-400/default-image.jpg
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      height:300,
      width:400
    }]}
  />

  // Loading image from an absolute file path with no transformations - https://www.custom-domain.com/default-image.jpg
  <IKImage
    src="https://www.custom-domain.com/default-image.jpg"
  />

  // Using a new transformation parameter which is not there in this SDK yet - https://ik.imagekit.io/your_imagekit_id/tr:custom-value/default-image.jpg
  <IKImage
    path="/default-image.jpg"
    transformation={[{
      custom: 'value'
    }]}
  />
</IKContext>

The transformation prop is an array of objects. Each object can have the following properties. When you specify more than one object, each object is added as a chained transformation. For example:

// It means first resize the image to 400x400 and then rotate 90 degree
transformation = [
  {
    height: 400,
    width: 400
  },
  {
    rotation: 90
  }
]

See the complete list of transformations supported in ImageKit here. 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.

Adding overlays

ImageKit.io enables you to apply overlays to images and videos using the raw parameter with the concept of layers. The raw parameter facilitates incorporating transformations directly in the URL. A layer is a distinct type of transformation that allows you to define an asset to serve as an overlay, along with its positioning and additional transformations.

Text as overlays

You can add any text string over a base video or image using a text layer (l-text).

For example:

<IKImage
    path="/default-image.jpg"
    transformation={[{ "width": 400, "height": 300 },{ "raw": "l-text,i-Imagekit,fs-50,l-end" }]}
/>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-text,i-Imagekit,fs-50,l-end/default-image.jpg

Image as overlays

You can add an image over a base video or image using an image layer (l-image).

For example:

<IKImage
    path="/default-image.jpg"
    transformation={[{ "width": 400, "height": 300 },{ "raw": "l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end" }]}
/>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-default-image.jpg,w-100,b-10_CDDC39,l-end/default-image.jpg

Solid color blocks as overlays

You can add solid color blocks over a base video or image using an image layer (l-image).

For example:

<IKVideo
    path="/img/sample-video.mp4"
    transformation={[{ "width": 400, "height": 300 },{ "raw": "l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end" }]}
/>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/tr:h-300,w-400,l-image,i-ik_canvas,bg-FF0000,w-300,h-100,l-end/img/sample-video.mp4

Arithmetic expressions in transformations

ImageKit allows use of arithmetic expressions in certain dimension and position-related parameters, making media transformations more flexible and dynamic.

For example:

<IKImage
    path="/default-image.jpg"
    transformation={[{
        "height": "ih_div_2",
        "width": "iw_div_4",
        "border": "cw_mul_0.05_yellow"
    }]}
/>

Sample Result URL

https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=w-iw_div_4,h-ih_div_2,b-cw_mul_0.05_yellow

List of supported transformations

Chained Transforms

Chained transforms make it easy to specify the order the transform is applied. For example:

// Using chained transformation. First, resize and then rotate the image to 90 degrees.
<IKImage
  path="/default-image.jpg"
  transformation={[
    {
      height: 300,
      width: 400
    },
    {
      rotation: 90
    }
  ]}
/>

Lazy loading images

You can lazy load images using the loading prop. When you use loading="lazy", all images that are immediately viewable without scrolling load normally. Those far below the device viewport are only fetched when the user scrolls near them.

The SDK uses a fixed threshold based on the effective connection type to ensure that images are loaded early enough so that they have finished loading once the user scrolls near to them.

On fast connections (e.g 4G), the value of threshold is 1250px and on slower connections (e.g 3G), it is 2500px.

You should always set the height and width of the image element to avoid layout shift when lazy-loading images.

Example usage:

// Lazy loading images
<IKImage
  path="/default-image.jpg"
  transformation={[
    {
      height:300,
      width:400
    },
    {
      rotation:90
    }
  ]}
  loading="lazy"
  height="300"
  width="400"
/>

Low-quality image placeholders (LQIP)

To improve user experience, you can use a low-quality blurred variant of the original image as a placeholder while the original image is being loaded in the background. Once the loading of the original image is finished, the placeholder is replaced with the original image.

// Loading a blurred low quality image placeholder while the original image is being loaded
<IKImage
  path="/default-image.jpg"
  lqip={{active:true}}
/>

By default, the SDK uses the quality:20 and blur:6. You can change this. For example:

<IKImage
  path="/default-image.jpg"
  lqip={{active:true, quality: 40, blur: 5}}
/>

You can also specify a raw transformation if you want more control over the URL of the low-quality image placeholder. In this case, the SDK ignores quality and blur parameters.

<IKImage
  path="/default-image.jpg"
  lqip={{active:true, raw: "n-lqip_named_transformation"}}
/>

Combining lazy loading with low-quality placeholders

You have the option to lazy-load the original image only when the user scrolls near them. Until then, only a low-quality placeholder is loaded. This saves a lot of network bandwidth if the user never scrolls further down.

// Loading a blurred low quality image placeholder and lazy-loading original when the user scrolls near them
<IKImage
  path="/default-image.jpg"
  transformation={[{height:300,width:400},{rotation:90}]}
  lqip={{active:true}}
  loading="lazy"
  height="300"
  width="400"
/>

Overriding urlEndpoint for a particular image

You can use urlEndpoint prop in an individual IKImage to change url for that image. For example:

<IKContext urlEndpoint="https://ik.imagekit.io/your_imagekit_id">
  // Render an image using parent IKContext urlEndpont - https://ik.imagekit.io/your_imagekit_id/default-image.jpg
  <IKImage path="/default-image.jpg" />

  // Overriding urlEndpoint defined in parent IkContext - https://www.custom-domain.com/default-image.jpg
  <IKImage urlEndpoint="https://www.custom-domain.com" path="/default-image.jpg" />
</IKContext>

Video resizing

The IKVideo component renders a video tag. It is used for rendering and manipulating videos in real-time. IKVideo component accepts the following props:

Basic video resizing examples

<IKContext urlEndpoint="https://ik.imagekit.io/demo/your_imagekit_id">
  // Video from related file path with no transformations - https://ik.imagekit.io/demo/your_imagekit_id/sample-video.mp4
  <IKVideo
    path="/sample-video.mp4"
  />
  // Video resizing - https://ik.imagekit.io/demo/your_imagekit_id/tr:w-h-300,w-400/sample-video.mp4
  <IKVideo
    path="/sample-video.mp4"
    transformation={[{
      height:300,
      width:400
    }]}
  />
  // Loading video from an absolute file path with no transformations - https://www.custom-domain.com/default-video.mp4
  <IKVideo
    src="https://www.custom-domain.com/default-video.mp4"
  />
  // Using a new transformation parameter which is not there in this SDK yet - https://ik.imagekit.io/demo/your_imagekit_id/tr:custom-value/sample-video.mp4
  <IKVideo
    path="/sample-video.mp4"
    transformation={[{
      custom: 'value'
    }]}
  />
</IKContext>

The transformation prop is an array of objects. Each object can have the following properties.

// It means first resize the video to 400x400 and then rotate 90 degree
transformation = [
  {
    height: 400,
    width: 400,
    rt: 90
  }
]

File upload

The SDK provides the IKUpload component to upload files to the ImageKit Media Library.

IKUpload component accepts the following props. These options are better explained in the ImageKit Upload API documentation.

Make sure that you have specified authenticator and publicKey in IKUpload or in the parent IKContext component as a prop. The authenticator expects an asynchronous function that resolves with an object containing the necessary security parameters i.e signature, token, and expire.

Abort upload

ref can be passed to obtain access to the IKUpload component's instance. Currently, only 1 abort method is supported to be called on the ref. Calling the abort method will abort the upload if any is in progress.

Sample Usage

const onUploadStart = (evt) => {
  console.log('Started', evt);
};

const onUploadProgress = (evt) => {
  console.log('Progress: ', evt);
};

const onError = (err) => {
  console.log('Error');
  console.log(err);
};

const onSuccess = (res) => {
  console.log('Success');
  console.log(res);
};

<IKContext
  publicKey="your_public_api_key"
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
  authenticator={()=>Promise} 
  // This promise  resolves with an object containing the necessary security parameters i.e `signature`, `token`, and `expire`.
>
  <IKUpload
    onError={onError}
    onSuccess={onSuccess}
    onUploadStart={onUploadStart}
    onUploadProgress={onUploadProgress}
    transformation={{
      pre: 'l-text,i-Imagekit,fs-50,l-end', 
      post: [
        {
          'type': 'transformation', 
          'value': 'w-100'
        }
      ]
    }}
  />
</IKContext>;

Custom Button Example, using ref

const reftest = useRef(null);

const onError = (err) => {
  console.log('Error');
  console.log(err);
};

const onSuccess = (res) => {
  console.log('Success');
  console.log(res);
};

<IKContext
  publicKey="your_public_api_key"
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
  authenticator={()=>Promise} 
  // This promise  resolves with an object containing the necessary security parameters i.e `signature`, `token`, and `expire`.
>
  <IKUpload
    onError={onError}
    onSuccess={onSuccess}
    ref={reftest}
    style={{display: 'none'}} // hide default button
    transformation={{
      pre: 'l-text,i-Imagekit,fs-50,l-end', 
      post: [
        {
          'type': 'transformation', 
          'value': 'w-100'
        }
    ]
    }}
  />
  <h1>Custom Upload Button</h1>
  {reftest && <button className='custom-button-style' onClick={() => reftest.current.click()}>Upload</button>}
</IKContext>;

IKCore

Accessing the underlying ImageKit javascript SDK is possible using the IKCore import. For example:

import { IKCore } from "imagekitio-react"
// Generate image URL
var imagekit = new IKCore({
    publicKey: "your_public_api_key",
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
});
//https://ik.imagekit.io/your_imagekit_id/endpoint/tr:h-300,w-400/default-image.jpg
var imageURL = imagekit.url({
    path: "/default-image.jpg",
    urlEndpoint: "https://ik.imagekit.io/your_imagekit_id/endpoint/",
    transformation: [{
        "height": "300",
        "width": "400"
    }]
});

Error Handling

You can use ErrorBoundary to handle errors anywhere in their child component tree. Log those errors or display a fallback UI instead of the crashed component tree. For example:

// urlEndpoint should be present in IKImage or parent IKContext component; otherwise, it will throw an error. For example:
<ErrorBoundary>
  <IKImage
    path = "/default-image.jpg"
    transformation={[
      {
        height:300,
        width:400
      }
    ]}
  />
</ErrorBoundary>

Support

For any feedback or to report any issues or general implementation support, please reach out to support@imagekit.io

Links

• Documentation
• Main website

License

Released under the MIT license.