# XT Adaptive Images User's Guide

# Overview and Quick Setup

Once XT Adaptive Images plugin is installed and enabled, images will be resized according to the resolutions and stored into the cache path; and finally image filenames are replaced in the page to the new generated files. If there is a configurated CDN, the new images are defined to be loaded from it.

By default, resolutions are 1382,992,768,480, these are the break-points to use (screen widths, in pixels). The cache path is, by default, media/media/xt-adaptive-images.

# How it works


XT Adaptive Images works in a similar way to adaptive-images.com (opens new window). However, as the extension is developed for Joomla!, some limitations have been resolved. It does support Content Delivery Networks and there is no need to configure website's .htaccess file (hence no difference between Apache or nginx configuration).

XT Adaptive Images does a number of things depending on the scenario the script has to handle but here is a basic overview of what happens when you load a page:

  1. The HTML starts to load in the browser and a snippet of JS in the writes a session cookie, storing the visitor's screen size in pixels.
  2. Joomla! generates each page, and calls XT Adaptive Images plugin (onAfterRender).
  3. XT Adaptive Images parses the page looking for images, and calls a modified version of adaptive-images.com (opens new window) script.
  4. adaptive-images.com (opens new window) script then does some intelligent thinking which can cover a number of scenario's but I'll illustrate one path that can happen: It looks for a cookie and finds that the user has a maximum screen size of 480px. It compares the cookie value with all $resolution sizes that were configured, and decides which matches best. In this case, an image maxing out at 480px wide. It then has a look inside the /media/xt-adaptive-images/480/ folder to see if a rescaled image already exists. We'll pretend it doesn’t - then it goes to the actual requested URI to find the original file. It checks the image width. If that's smaller than the user's screen width it sends the image. If it is larger, the PHP creates a down-scaled copy and saves that into the /xt-adaptive-images/480/ folder ready for the next time it is needed, and sends it to the user. It also does a few other things when needs arise, for example: Detects Retina displays. You can choose to serve high DPI images to those displays if you want, by using an alternate line of JavaScript. It handles cases where there isn't a cookie set; mobile devices will be supplied the smallest image, and desktop devices will get the largest. It compares time-stamps between the source image and the generated cache image - to ensure that if the source image gets updated, the old cached file won’t be sent.
  5. If no image is generated, the image is not modified.
  6. If an adapted image is generate, the new image replaced the original image.
  7. Additionally, if there is at least one CDN is configured, the CDN Url is appended to load the image from the new location.

# I visit the site with a Galaxy S5 phone, but resized images are not generated or displayed, why?

The plugin has two essential functionalities. First, it detects the display size and offers an approximate default image size (src) based on estimation. Secondly, it provides a set of images of different sizes (srcset) to the browser. The browser knows everything to pick the right image (e.g, pixel density) to select a picture with a higher resolution. Different browsers and mobile devices can choose different image sizes. The modern browsers process all the offered photographs and choose the best alternative.

For example, an image will be resized to 480px and stored in the folder. If you create a Page where the same image has to be shown to fit a 960px-wide design, the browser will 2X scale the image.

Finally, device resolution plays a role that can increase the image width requirements. Here you can check how the new width is calculated: https://github.com/MattWilcox/Adaptive-Images/blob/master/adaptive-images.php#L252 (opens new window)

# Basic Configuration

XT Adaptive Images - Basic Configuration

# Resolutions

Set breakpoints to match your CSS's Media Queries (they must also match your device-dependent cache configuration). By default, 1382, 992, 768, 480. If you are doing a responsive design then you ought to make these values the same as your CSS's. You can have as many or as few as you'd like, e.g.,, 1200, 768, 480.


As a handy configuration, if you define one resolution, e.g.,, 480, all images will be restricted to 480px.

# PRO Cache Path

Change the name and location of the media/xt-adaptive-images folder. This path is relative to the Joomla! root.

# Jpg Quality

Quality can be any number from 0 to 100, with 100 being the best (but with largest file-size). Note that you can not control the quality at which GIF or PNG images are saved.

# Sharpen

When set to TRUE Adaptive Images will perform a subtle sharpening on any images that it rescales.

# Detect Retina displays

You can choose to serve high DPI images to those displays.


A word of caution: such images will look very sharp, but they'll still be pretty big and slow to load.

# CDN Configuration

In addition, XT Adaptive Images has the combined features to allow the integration with a Content Delivery Network (CDN). Hence, once the images are generated into the Cache Path, the CDN Url domain is pre-appended to the images in the page.


A content delivery network or content distribution network (CDN) is a large distributed system of servers deployed in multiple data centers across the Internet. The goal of a CDN is to serve content to end-users with high availability and high performance. CDNs serve a large fraction of the Internet content today, including web objects (text, graphics and scripts), downloadable objects (media files, software, documents), applications (e-commerce, portals), live streaming media, on-demand streaming media, and social networks. Reference: Content delivery network, from Wikipedia (opens new window).

XT Adaptive Images - CDN Configuration


If you need to exclude an area from the CDN, you can define it with the following tags: {nocdn}...{/nocdn}.

# Site Root

The root of your website that you have connected to your CDN server.

# CDN Domain

The domain of your CDN Server.

# PRO Handle HTTPS urls

Select to also handle https urls (secure urls).

# PRO Extra CDN Sets

Up to 5 additional CDN domains to distribute files according to associated File Types.

XT Adaptive Images - CDN Configuration

# PRO Lazy Load Images

  • Enable Lazy Load Images: Lazy Load is delays loading of images in long web pages. Images outside of viewport are not loaded until user scrolls to them.
  • Image class: Class to detect images to be lazy loaded. By default, xt-lazy-img. You can define more than one, for example: img-polaroid,xt-lazy-img.

# Platform Specific Caching (Joomla 3 and Joomla 4)

By default, Joomla! generates a single cache for the whole site, regardless of the client device.

Nowadays, Joomla! is increasingly generating HTML output where mobile differs from other devices. In this case, a device-specific cache is required.

# Alternative 1: JotCache (Joomla 3)

JotCache Configuration for Mobile

# Alternative 2: Joomla'a Platform Specific Caching

For Joomla! 3.5.1 or superior, including Joomla 4: Joomla has included a new cache mode: Platform Specific Caching. This new feature provides a similar functionality:

Platform Specific Caching

# Limitations

Last Updated: 2/29/2024, 2:54:14 PM