Responsive images in Kentico

I want to share my method of handling responsive images with my responsive website implementations in Kentico. As we continue to build responsive sites, one of the key players is always performance aka load time.

With almost every website out there today, large images are going to be apart of the design, most commonly a large hero image. For the purpose of this post, we’re going to use a hero image as our example. Let’s imagine the design we need to implement has a large hero image on the homepage for desktop and a smaller version for mobile and tablet.

Two of the easiest performance improvements we can make is, 1.) limit the number requests we have and 2.) make sure the file size is as small as possible in our requests.

We know we’re going to need a large hero image for desktop but keep the file size small for mobile and tablet. We know we can’t make three separate requests for a mobile, tablet and desktop version of the hero image because that goes against our performance rule to limit the number of requests we have.

There are some JavaScript solutions out there that eliminate the need for three requests but it still requires the content editors to create three separate versions of the image. Or there is this solution from a devnet article but this still requries three separate assets.

The CurrentDevice and Width solution

Lately I’ve been using the CurrentDevice.ScreenPixelsWidth macro in combination with the width querystring  parameter to resize the image based on the width of the device.

/Library/getmedia/ed0be744-9e70-4056-8c7d-91fc5087813c/Hero.jpg.aspx?width={% CurrentDevice.ScreenPixelsWidth #%}

In the example above, we’re using the default permanent url from the media library image and appending the CurrentDevice.ScreenPixelsWidth macro to the width querystring.

Width Querystring

Let’s look at what the Kentico documentation says about the width querystring and what it does if we pass a width value that is smaller than the original width of the image.

“Every time you resize an image to a smaller size, the system makes a new copy of this image with this dimensions in the __thumbnails folder, which is located in the original image's folder. The images are resized into smaller files to save bandwidth.” - Kentico Documentation

Perfect. Kentico will generate a copy of our image, save it to a _thumbnail folder in the media library and serve that image to the user instead of our larger image. Hopefully you can see where I’m going with this, serving a smaller version of the image to devices with smaller resolutions.

CurrentDevice Macro

Kentico integrates with a 3rd party component called, which means their CurrentDevice object has all of the 51Degrees properties available to you. I would recommend looking at the entire list of properties available.

For our solution, we’re using the ScreenPixelsWidth property to detect the width of the device viewing our site. Let’s say we’re viewing our website on a mobile device. The macro is going to detect our width as 640px, which means our example URL is now rendered like this:


Knowing what the width querystring does in Kentico, we know this will save a copy of our image with a width of 640px. This is much better than making three separate requests for mobile, tablet and desktop versions of the image and much better than serving a desktop sized image to mobile and tablet.

Seeing it in action

Okay, so we have our macro and width querystring in place, now let’s review what this looks like on a page load.

We’re going to look at the list of network requests for the desktop first. I’m using Google Chrome Developer Tools and looking at the Network tab

We can see the biggest file size on this page is the hero image with a file size of 634kb.  Not bad but not ideal for a mobile device with no wifi.

The next set of network requests we’re going to look at is for a mobile device using the Developer Tools iPhone emulator.

Again, we will see the biggest file size in the list of requests is the hero image but notice this time the file size is 281kb! Kentico reduced the file size by 55%! :fire: emoji. That is what we’re looking for. This is a huge performance improvement.

What I love about this solution is its one image. The content editors have to create one asset and upload it and we can utilize Kentico to do the rest with minimal code.

Permanent media URLs in Kentico

It’s important to note that one of the keys to this approach is using permanent media URLs in Kentico. You will need to configure your Kentico media settings to use permanent URLs.

In order to do to this go to: Settings > Content > Media > Use Permanent URLs.

This will configure the Kentico media library file URLs to be generated as permanent links, which means every time Kentico renders your media file URL, it will use the permanent URL format and not the non-permanent by default.

Let’s look at the difference between a permanent media file URL and one that isn’t permanent.

Non-permanent URL:

Permanent URL:

Anytime you insert a media file through an editable text web part, it will use the permanent URL or if you use the Media Selection form control on a custom page type, it will render the permanent URL in your transformation.

I like to use the Media Library for all images, so I only configure the media setting but you can create permanent URLs for pages and attachments as well.

Global image resizing

If you have permanent URLs configured, you can set all images in Kentico to resize based on device profile.

Go to: Settings > Content > Content Management > Resize images according to device profile

This may override the default height and width parameters and use the device width for the maxsidesize parameter. This could save us time.  You can always disable device profile resizing by adding the resizemode=1 parameter to the GetFile URL.

For me, I'm a bit of a control freak and would like to decide where I implement this method instead of using a global setting. You will need to decide if a global approach like this will work for your project.


I hope you found this method useful. What I love about this solution is that we can keep the asset creation to a minimum for the editors and we can take advantage of some really useful built-in Kentico functionality to improve performance on our responsive sites. I really encourage you to explore this solution on your next project.

There are many ways to do things on the web nowadays, so if you have an alternative method to handling responsive images, I would love to hear them in the comments below. Or if you have any improvements we could make on this solution, I would love to hear those as well!

Share your thoughts