@burst/imagekit

The ultimate, lightweight solution for using ImageKit images in a JavaScript project.

React component

This module provides an <ImagekitImage /> component that automates the optimization of images.

Full width

If you have a full-width (100vw) image, then it's very easy to create a dynamic image.

import { ImagekitImage } from '@burst/imagekit';

<ImagekitImage
  src="https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg"
  breakpoints={[240, 600, 1000]}
  aspectRatio={16 / 9}
/>;

This will let the browser choose between a 240px, 600px and 1000px image. If you would view this image on a screen of 500px with a retina screen (device pixel ratio of 2) then it would show the 1000px version.

This logic is fine for most full-width or almost-full-width images.

Dynamic width

If you have an image where the aspect ratio is always the same, but the width can differ between viewports, you can use the default html sizes tag to differ between images.

import { ImagekitImage } from '@burst/imagekit';

<ImagekitImage
  src="https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg"
  breakpoints={[240, 600, 1000]}
  aspectRatio={16 / 9}
  sizes="(min-width: 800px) 50vw, 100vw"
/>;

Another option is to implement this into the breakpoints array. Instead of providing a simple number, you can provide a tuple. The first item will be the window width, the second item is the size you expect the image to be in until that breakpoint.

import { ImagekitImage } from '@burst/imagekit';

<ImagekitImage
  src="https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg"
  breakpoints={[200, [600, 300], [1000, 500], 700]}
  aspectRatio={16 / 9}
/>;

This results in the following behaviour:

| Window size | Image size | | -------------- | ---------- | | 0px - 200px | 200px | | 201px - 600px | 300px | | 601px - 1000px | 500px | | 1001px + | 700px |

The following component would render exactly the same result:

import { ImagekitImage } from '@burst/imagekit';

<ImagekitImage
  src="https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg"
  breakpoints={[200, 300, 500, 700]}
  aspectRatio={16 / 9}
  sizes={`
    (min-width: 1001px) 700px,
    (min-width: 601px) 500px,
    (min-width: 201px) 300px,
    200px
  `}
/>;

Dynamic aspect ratio

If the aspect ratio is not the same between all breakpoints, you can define a width and aspect ratio for the breakpoints that are different.

For example, to render a 1:1 aspect ratio from 0 - 600px and a 16:9 aspect ratio from 601px and more, you would use this:

import { ImagekitImage } from '@burst/imagekit';

<ImagekitImage
  src="https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg"
  breakpoints={[
    [200, { ar: 1 / 1 }],
    [600, { ar: 1 / 1, w: 300 }],
    [1000, 500],
    700,
  ]}
  aspectRatio={16 / 9}
/>;

This would generate a picture element with two sources, one for the 1:1 version and one for the 16:9 version.

Under the hood

Whenever possible, this component will just render an <img> tag with the srcset and sizes attribute set. This is enough to let the browser choose the right version of an image intelligently. It will automatically take care of image caching (so, if it has a large image already cached, it will not download a lower-quality image) and will take care of the device image

If however the aspect ratio changes between breakpoints (for example, mobile images are always 1:1 and desktop images are always 1:2) it will use an <picture> element with <source> in it. This will force the browser to use the right aspect ratio at the right breakpoints.

For more information, check out these awesome resources:

• Responsive Images: If you’re just changing resolutions, use srcset. on the difference between an <img> and <picture> element
• MDN - Responsive images for a general guide to responsive images

Manual ImageKit URL creation

The createImagekitUrl() function can be used to generate URLs manually.

import { createImageUrl } from '@burst/imagekit';

const simpleUrl = createImageUrl({
  src: 'https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg',
  transformations: {
    w: 200,
    ar: 16 / 9,
  },
});

This will make 'simpleUrl' an image with a width of 200 pixels and an height of 113 pixels to maintain a 16:9 aspect ratio. In this case, it would return https://ik.imagekit.io/demo/medium_cafe_B1iTdD0C.jpg?tr=w-200,h-113.

For more examples, check out the tests created for this function.

Drupal focal_point integration

This module has been fully optimized for using images with a focal point provided by the Drupal focal_point module.

For this, the right information should be passed into the src argument of the <ImagekitImage /> or the createImageUrl().