Optimizing images for web

Learn how to transform your images using the Delivery API.

Optimizing images is important for running a performant site with faster loading times and better bandwidth. In this tutorial, you'll learn how to use the image transformation via the Delivery API to display images based on the different screen sizes, device pixel ratio and more.

Delivery API allows you to perform dynamic transformations on your images by changing the URL of the image. For example, instead of uploading multiple versions of the same image, you can use one asset and resize it to fit different device resolutions via image transformation.

1. Setting up the limitations in the app

Before you start working with images via the Delivery API, we recommend configuring appropriate limitations for the elements in your content types. This way, content editors can only publish the content items containing the images in the right format and within the set dimensions.

In the content type, you can set the limitations for the Asset and Rich Text elements to "Adjustable images" only. This means that only image formats that support image transformation can be added to the element. The adjustable image formats are jpeg, png, gif, and webp.

You might also want to set the file size limit and the limitations for the dimensions of the image. By doing so, you can make sure that the uploaded images are of appropriate size when used in the content items.

Adjustable images in the content type

Adjustable images in the content type

Now that the limitations are set, the content editors can start adding assets to the content items.

2. Getting the image URL

To get the URL of your image, you need to retrieve the content item that contains the image via the Delivery API.

To get a single content item:
https://deliver.kenticocloud.com/<project_id>/items/<content_item_codename>

To get all the items:
https://deliver.kenticocloud.com/<project_id>/items

Adjustable images can be used in the Asset elements and in the Rich text elements of the content items.

  • When in the Asset element, the absolute URL for the image can be found in the url attribute of an asset object returned in the JSON response.
  • When in the Rich Text element, the absolute URL for the image can be found in the url attribute of the images object and in the formatted text of the value attribute.

For the purpose of this tutorial, we've created a simple content item called "Landscapes" containing the images we want to transform. Below is an example of the Delivery API response when requesting the "Landscapes" content item with the images in the Asset element as well as the Rich text element. This JSON example has been stripped for brevity. See the whole JSON file.

{
    "item": {
        "system": {
                  // omitted from the response for brevity
        },
        "elements": {
            "cover_photo": {
                "type": "asset",
                "name": "Cover photo",
                "value": [
                    {
                        "name": "daylight.jpg",
                        "type": "image/jpeg",
                        "size": 1894816,
                        "description": "Person sitting on the wooden pier",
                        // image URL
                        "url": "https://assets-us-01.kc-usercontent.com:443/b744f382-bfc7-434d-93e7-a65d51249bc7/cc0afdc7-23d7-4fde-be2c-f58ad54d2934/daylight.jpg"
                    }
                ]
            },
            "content": {
                "type": "rich_text",
                "name": "Content",
                "images": {
                    "8efa6e46-c755-48fe-9b42-9e03835e3784": {
                        "image_id": "8efa6e46-c755-48fe-9b42-9e03835e3784",
                        "description": "Lago di Pilato (Pilate lake) located in Sibillini Mountains, among the Apennines.",
                        // image URL
                        "url": "https://assets-us-01.kc-usercontent.com:443/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg"
                    }
                },
                "links": {},
                "modular_content": [],
                // image URL
                "value": "<figure data-asset-id=\"9e5803e8-48d7-45db-87da-11de18bc9a99\" data-image-id=\"9e5803e8-48d7-45db-87da-11de18bc9a99\"><img src=\"https://assets-us-01.kc-usercontent.com:443/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg\" data-asset-id=\"9e5803e8-48d7-45db-87da-11de18bc9a99\" data-image-id=\"9e5803e8-48d7-45db-87da-11de18bc9a99\" alt=\"Lago di Pilato (Pilate lake) located in Sibillini Mountains, among the Apennines.\"></figure>"
            }
        }
    },
    "modular_content": {}
}

The appropriate image URLs we've gathered via the Delivery API request can be seen below. You can either use these URLs to try out the image transformation or get your own image URLs by following the previous steps.

Image URL #1: https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/cc0afdc7-23d7-4fde-be2c-f58ad54d2934/daylight.jpg

Image URL #2: https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg

Now that we have the image URLs, let's do some magic.

3. Displaying transformed images

Images are part of responsive web design and as such can highly contribute to the site's bandwidth and its loading speed. In this section, we will work with a typical website scenario. The sample website contains a header image and a content image inside the content column. This site would work well on a wide screen device, such as a laptop or a desktop. The issues might arise once you open the page on a narrow screen device, such as your mobile phone. Ideally, you would want the images to adjust to the screen resolution and in case of the header image, to only see the cropped version. And this is where the image transformation comes into the picture (literally).

A simple website containing a header image and a content image.

A simple website containing a header image and a content image.

With adjustable images, you can solve two problems at once. In the header image, you'll work with the art direction problem. In other words, you will adjust the image to the different screen widths and use the crop fit mode to display the right portion of the image. In the content image, you will be solving the resolution switching problem, i.e., supporting multiple display resolutions based on the device pixel ratio (dpr).

Different solutions

The HTML image features used in this tutorial are one of the many possible solutions to the art direction and the resolution switching problems. We recommend you to experiment and find what suits you and your website the best.

HTML elements and attributes

In this section, we will briefly go through the HTML elements and attributes that you'll be using throughout this tutorial. If you're already familiar with them, feel free to skip ahead to the Header image transformation section.

  • srcset – defines the set of images for the browser to choose from, and what size each image is.
  • sizes – defines a set of media conditions, e.g. screen widths, and indicates what image size would be best to choose, when certain media conditions, such as "max-width", are true. The last slot width has no media condition — this is the default that is chosen when none of the media conditions are true.

These attributes will provide the web browser with additional source images along with hints to help the browser pick the right one. Note that older browsers that don't support these HTML features will ignore them and load the image referenced in the src attribute.

Learn more about the HTML <img> element on MDN Web Docs.

<img srcset=".../lake.jpg?w=400&h=200 400w,
             .../lake.jpg?w=600&h=250 600w,
             .../lake.jpg?w=800&h=300 800w"
     sizes="(max-width: 400px) 360px,
            (max-width: 600px) 560px,
            800px"
     src=".../landscapes.jpg" alt="a geothermal field to the east of Reykjahlid">

Note: In the <head> of the HTML document you'll find the line <meta name="viewport" content="width=device-width"> which forces mobile browsers to adopt their real viewport width for loading web pages. Learn more about using the viewport meta tag on MDN Web Docs.

Header image transformation

What you want to do with the header image is to crop the image where it's appropriate and then change the image size according to the different viewports.

With the HTML basics down, you can start with applying the image transformation methods to the image URLs. Specifically, you'll be using the width (w) and height (h) parameters for resizing and the resize fit mode (fit) for a better fit within the page.

<img 
     srcset="https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/cc0afdc7-23d7-4fde-be2c-f58ad54d2934/daylight.jpg?w=400&h=200&fit=crop 400w, 
             https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/cc0afdc7-23d7-4fde-be2c-f58ad54d2934/daylight.jpg?w=600&h=250&fit=crop 600w, 
             
             <!-- See the Interactive example section to view the full HTML code -->
            "
     
     sizes="(max-width: 400px) 360px,
            (max-width: 600px) 560px,
            (max-width: 800px) 760px,
            (max-width: 1000px) 960px,
            1200px"
     
     src="https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/cc0afdc7-23d7-4fde-be2c-f58ad54d2934/daylight.jpg" alt="Mountains">

By using the width (w) and height (h) parameters, you can change the dimensions of the image to fit the different viewports. For example, adding the w=400&h=200 query to the image URL downsizes the image to the set dimensions. Note that the actual output dimensions might differ depending on the resize fit mode you choose.

Next, you'll be using the crop fit mode to achieve the desired header image look. Adding fit=crop to the query after the w and h parameters will crop the image according to the set dimensions. See the difference between the default clip mode and the chosen crop mode to see how it changes the image appearance with the same dimensions set (w=800&h=300).

Different resize fit modes applied to the same image.

Different resize fit modes applied to the same image.

In the srcset attribute, you need to add the image URL followed by the inherent width of the image, which in this case, is 400w. Note that this uses the w unit which represents the true width of the image.

In the sizes attribute, you need to specify the media conditions, in this case, the maximum width and the width of the slot that the image will fill when the condition becomes true.

For example, when the (max-width: 400px) condition is true, the 400px slot will be chosen and the /daylight.jpg?w=400&h=200&fit=crop version of the image will be loaded on the page.

Saving bandwidth

The full-size daylight.jpg picture has the dimensions of 4000×2025 and its size is 1.56MB. In comparison, the 400×200 version is only 24.66Kb. Using the image transformation, especially when the website contains more than a few images, can save you quite a lot of bandwidth.

Content image transformation

Let's continue with the content image. With this image, you want to add support for high-resolution displays using pixel density descriptors, or the x descriptors in the srcset attribute.

Standard devices have a pixel density of 1, meaning the monitor has 1 device pixel per CSS pixel, while newest HiDPI monitors, including “Retina” displays, have a higher density. To adjust the image depending on the display it's being viewed at, you will use the device pixel ratio (dpr) parameter.

<img srcset="https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg?w=600&dpr=1,
             
             https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg?w=800&dpr=2 2x,
             
             https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg?w=1200&dpr=3 3x"
             
     src="https://assets-us-01.kc-usercontent.com/b744f382-bfc7-434d-93e7-a65d51249bc7/5ad0a62a-1e5c-4cff-aa1b-fdc016efceee/adventure.jpg" alt="Daylight"> 

In this case, the sizes attribute is not needed, the browser simply determines what resolution the display is and serves the most appropriate image referenced in the srcset. So if the device accessing the page has a standard resolution display, with one device pixel representing each CSS pixel, the /adventure.jpg?w=600&dpr=1 version of the image will be loaded. Note that the 1x is implied, so you don't need to include it. If the device has a higher resolution of two device pixels per CSS pixel, the /adventure.jpg?w=800&dpr=2 image will be loaded.

The dpr parameter needs to be used with the width, height, or both the dimensions in order to work properly. In this example, only the w parameter is specified for the image.

Saving bandwith

Let's see how using the device pixel ratio in our image influences the bandwidth. The standard resolution display loads the w=600&dpr=1 version, which has the dimensions of 600×399 and 82.54Kb. When displaying the image on the HiDpi devices, the w=1200&dpr=3 version is loaded. This image version has the dimensions of 3600×2394 and 2.46Mb.

Interactive example

Check out our sample web page created in CodePen. We recommend you to play around with the page using your favorite web developer tools to see the page changing based on its width or device pixel ratio and look at the sizes of the retrieved images.

Summary

In this tutorial, you've learned the basics of optimizing images for web. But there is more to think about when delivering images using the image transformation. Delivery API gives you the ability to add additional operations, such as focal point crop or automatic format selection, to give you more control over your output images. And because they are defined in the URL, you can fine-tune your settings and make late-stage edits as decisions change.

What's next?