Optimize images for the web

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.

By optimizing your images, Google is also likely to crawl and index your images faster for Google image search.

1. Setting up the limitations in the app

Before you start working with images via the Delivery API, we recommend configuring proper 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.

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 image URL, copy the URL directly from the asset details in the UI.

You can also get the image URL when retrieving the content item that contains the image via the Delivery API. See the details in our image transformation reference.

The image URLs used in this tutorial can be seen below. You can utilize 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).

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 part 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).

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 <img> element in the MDN web docs.

HTML
<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">
<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.

HTML
<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">
<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).

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.

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.

HTML
<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"> 
<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.

Interactive example

Check out our sample web page created in CodePen. We recommend you 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.