How to make images responsive with Uploadcare image transformations?

Follow this guide to get quick and convenient ways to use image transformations in your project.

Responsive image on mobile devices, laptop, and desktop

Select one or several solutions that suit your needs. Either connect a ready-made library or take advantage of Uploadcare’s URL API and compression algorithms in order to make your pages lightweight and responsive.

We recommend using the <picture> element for all informative and functional images as it extends the <img> element and provides a way to add media queries, select alternative media formats, and allow art direction.

Connect a script to deliver optimized images to users automatically

Probably the easiest and most universal way to optimize images of your website on the fly is by connecting the Adaptive Delivery to your project. Image optimization is performed on the fly at the time of user requests and the results get cached on our CDN nodes. It also lets you either store images with Uploadcare or keep them on your hosting.

See our documentation for detailed info. There are three steps:

  1. Connect the Adaptive Delivery JS script (remember to use your own public API key instead of YOUR_PUBLIC_KEY).
      (function(src, cb) {
      var s = document.createElement('script'); s.setAttribute('src', src);
      s.onload = cb; (document.head || document.body).appendChild(s);
    })('', function() {
  1. Whitelist image sources, if your images are hosted outside of Uploadcare CDN. On your Uploadcare dashboard, go to ”Settings” — ”Proxy”, click “Connect”, and add domains you are planning to use.

  2. Replace src attributes in your <img> tags with data-blink-src attributes:

<img data-blink-src="" alt="">
     <!-- also works for background images -->
    <div data-blink-src="">
      This block contains a banner.
    <!-- you can use file UUID for images stored on Uploadcare CDN -->
    <img data-blink-uuid="36f90908-afb9-4e0a-b254-1b769faf8f3a"
    data-blink-quality="smart-retina" alt="">

You can also add various filters and effects and select various delivery options that make images responsive, optimized, and lazy-loaded.

Set automatic image format and quality on delivery

When you store your images on Uploadcare’s CDN, you get access to automatic smart conversion and compression that are available via URL operations. These features are handled by our own highly efficient compression algorithms.

Take an original image:

Greenpaws the Chameleon holding a branch

You can also trust our CDN to select the image quality for user devices and browsers. -/quality/lightest/ will get maximum image compression without any noticeable visual artifacts. We recommend you set -/quality/lightest/ for screens with high DPI:

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->
<img src="" alt="">
{/* for retina screens, add -/quality/lightest/ */}
<img src="" alt="">

Make a single image responsive

Take a look at a more traditional approach that doesn’t require any JS.

  • Resize your picture to fit the widest container. We recommend using resizing using one dimension to preserve the aspect ratio.
  • Set width: 100%; declaration to the image block, so that the image adapts to the container width automatically.

Say, your original image resolution is 4928 x 3280 px, and the file size is 1.85 MB:

Also, your container width is limited to 1200 px on the widest screens. Use the resize operator in the image URL in order to reduce the resolution of the image and its file size:

Add the updated image URL to the src attribute of the <img> tag:

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

<img src="" alt="">
 img {
   width: 100%;
   height: auto;

Play around with this live example and make sure to check the device mode and the network tab in DevTools to see the way the image properties are changing.

Here, the original image width has been reduced to 1000px, and the file size has been reduced to just 125 KB.

Since we're going to spend some time with our green chameleon pal, let's give him a name — Greenpaws.

Optimize the image for high pixel ratios

Set an additional version of the image for HiDPI screens with the srcset attribute of the <img> element and the x descriptor.

Retina screens have a pixel ratio of 2. To optimize for them:

  • multiply the resize value by 2
  • reduce the image quality using the quality operation
  • add the alternative image link to the srcset attribute followed by the 2x descriptor that ties the image to devices with 2x pixel ratio
<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

  srcset=" 2x"
  alt="Greenpaws the Chameleon">

Here is a live example that uses the same image of Greenpaws on Uploadcare CDN to produce an alternative retina version of it:

However, this 2400px wide image is hardly necessary for an iPhone version of the website that needs only 320px width by 2x pixel ratio, which gives us 640px.

If you want to adapt your images to various screen widths in the smartest way, continue to the next section.

Optimize an image for different screen widths and breakpoints

You may use either an expanded new <picture> HTML element, or a traditional <img> element.

Using <img>

Use URL API to:

  • create various resized versions of the image for different screen widths
  • add them to the srcset attribute followed by a w descriptor with screen width in pixels
  • add the sizes attribute to the <img> element to set primitive media conditions. It should contain information on how much of the viewport will be occupied by the image

Here is an expanded example from the previous section that now contains various versions of an image optimized for many different widths in w descriptors:

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

<img src=""
  srcset=" 320w, 450w, 640w, 750w, 800w, 900w, 1000w, 1200w, 1500w, 1600w, 2000w"
  sizes="(min-width: 1200px) 50vw, 90vw"
  alt="Greenpaws the Chameleon">

The x descriptor is incompatible with the w descriptor.

In this example, this value of sizes tells the browser to set the image width to 50vw if the viewport width is 1000px or more; otherwise, occupy most of the screen width: sizes="(min-width: 1200px) 50vw, 90vw"

Take a look at this live example to see our pal Greenpaws adapt to various screen sizes, and make sure to try some of your own pictures in it.

Using <picture>

The semantic <picture> element expands <img> and offers more ways of manipulating the images because it allows you to use actual media queries.

Use <source> elements within the parent <picture> element. Include a srcset attribute that can have sizes and media attributes.

Use URL API to:

  • create various resized versions of the image for different screen widths
  • add them to the srcset attributes of <source> elements
  • add a media attribute to specify media conditions
  • add a sizes attribute to specify the portion of the screen occupied by the image
  • add at least one version of an image to the child <img> element that will act as a fallback.

Here is an example of how the <picture> element may be used:

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

    media="(max-width: 450px) and (orientation: portrait)">
    srcset=" 320w, 450w, 640w, 750w, 800w, 900w, 1000w, 1200w, 1500w, 16000w, 2000w"
    media="(min-width: 1200px)">
  <img src="" alt="Greenpaws the Chameleon">

The media attribute allows you to specify media queries, and it will allow the browser to select the most suitable source for every kind of device and viewport you have specified.

Now Greenpaws can get different display versions based on screen orientation:


Using CSS

You can also set different versions of an image with breakpoints using CSS media queries.

That might be useful if an image is not part of the HTML content — like a banner or a background image. Use the image-set() CSS function to set new image versions, say, for normal and HiDPI screens:

/* replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID */
  background-image: image-set(
  url("") 1x,
  url("") 2x

Try out this live example:

Or use this ready-made SCSS function for the same purpose:

Crop to object and enable art direction

Scale instead of resizing

Normally, your image ends up looking the same in portrait versions of devices, on desktops, and in landscape versions. That may be fine for square images, but the subjects of the wide images will probably end up looking too small on mobiles:

Landscape-oriented image resized on a smartphone

Automatically cropping the image to its object will help you resolve this issue:

Portrait-oriented resize works netter for the smartphone screen

To do that, take advantage of scale_crop operations instead of resizing the images and combine them with media queries.

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

    srcset=" 320w, 640w, 450w, 900w"
    media="(max-width: 450px) and (orientation: portrait)">

  <img src="" alt="Greenpaws the Chameleon">

Here is a live example that features our pal Greenpaws. To see this solution work, change your device mode to portrait in the DevTools and reduce the screen width:

Art direction

To make art direction possible, you’re going to need to create specific image views for different breakpoints. Use crop together with the resize operator to achieve this goal.

Say, you want to display a horizontal image with just the Greenpaws’ head on smartphones:

Horizontal image resized on a smartphone screen

Take the previous example and just change the scale_crop operator to the crop operator with the resize operator.

Modify your image links, so that the crop operation is followed by resize:

<!-- replace 36f90908-afb9-4e0a-b254-1b769faf8f3a with your image UUID -->

    srcset=",670/-/resize/320x/320.jpg 320w,,670/-/resize/640x/640.jpg 640w,,670/-/resize/450x/450.jpg 450w,,670/-/resize/900x/900.jpg 900w"
    media="(max-width: 450px) and (orientation: portrait)">

  <img src="" alt="">

Try resizing the viewport in this live example:

If your image contains a face, it's easy to use the crop by object operation without additional resizing.