Sitecore Adaptive Images

  0 rating
2/4/2013 12:18:56 AM
4/17/2015 1:39:14 PM
Source: GitHub
Provider: bv02 Inc.


This is a Sitecore port of the popular Adaptive Images script. This module detects a visitor's screen size and uses the built in Sitecore image features to deliver re-scaled versions of images if necessary. It is intended for use with responsive designs.

Why would I want this?:

  • Ensures you and your visitors are not wasting bandwidth delivering images at a higher resolution than the visitor needs.
  • Will work on your existing site, as it requires no changes to your mark-up.
  • Takes retina displays into account so that images are served based on a combination of screen size and pixel density.

    The users screen size is detected and added as a cookie with a small line JavaScipt that is added to the main layout file(s) in your Sitecore solution. Once the screen size (and pixel density) is detected then it is possible to deliver appropriately sized images to the user.

    There is a C# .NET port ( of the popular PHP based Adaptive Images script (, but this module scraps its image caching in favor of Sitecore's built in image caching.


    In order for this module to work you must add a line of JavaScript into the head of your main Sitecore layout file (Preferably before any other JS).

    The following line of JS should be added if you want the module to take high pixel density displays (like retina displays) into account:

    <script>document.cookie = '<%= Sitecore.Configuration.Settings.GetSetting("cookieName") %>=' + Math.max(screen.width, screen.height) + ("devicePixelRatio" in window ? "," + devicePixelRatio : ",1") + '; path=/';</script>

    Otherwise, you can use the following line of JS if you don't care about high pixel density displays and images will be served based solely on screen size.

    <script>document.cookie = '<%= Sitecore.Configuration.Settings.GetSetting("cookieName") %>=' + Math.max(screen.width, screen.height) + '; path=/';</script>

    The final step is either installing the module as a package through the installation wizard or downloading the source files, compiling the code, and dropping the dll and config files to your Sitecore solution.

    How does it work:

    This module implements a custom MediaProvider that hooks into Sitecore. Whenever an image is rendered from the Sitecore Media Library, it passes through this custom MediaProvider and a Max-width property is added to the image parameters (ex: ?mw=1382). Therefore, this module will only alter images that are referenced from the Media Library.

    For more information, check out my blog post regarding the module:


    • Documentation > Setup


      All you need to do is install the package on your Sitecore solution and add the following line of JavaScript  to the head section in your Sitecore layout file(s).

      The JavaScript should be added as high in the head of your main layout as possible, before any other JS:

      <script type="text/javascript">document.cookie = '<%= Sitecore.Configuration.Settings.GetSetting("cookieName") %>=' + Math.max(screen.width, screen.height) + '; path=/';</script>

      Config Parameters:

      The custom config file contains the hook that initializes a custom Media Provider and also contains settings for the module.

      The settings are as follows:

      resolutions - This defines the resolution break-points to use (screen widths, in pixels). You can have any amount of breakpoints. In theory each break-point will correspond to a cached version of images at that resolution.

      mobileFirst - If set to TRUE, this parameter will return the smallest resolution version of images in the event that the resolution cookie is not accessible. (Ex: If JavaScript is disabled) Also note that this module will attempt to detect if a visitor is on a desktop OS based on the user agent string. Even if this parameter is set to true, if a desktop OS is detected then it will be set to false and show the largest version of images.

      cookieName - This parameter sets the name of the cookie that will store the detected resolution.

    Release notes
    - Support has been added for retina displays. The resolution cookie now stores the pixel density along with the screen width.

    - There was a problem with the previous version that has been fixed. The custom media provider was causing a max-width querystring parameter to be added to images in the rich-text editor. Now the custom media provider will only run on the live site.

    - A new "maxWidth" parameter in the config file allows you to set a maximum width for images on a site. This can be useful if your site's layout is, for example, 1000px. Then you can set the parameter so that no images are rendered larger than the site layout width. 

    - Here are new parameters in the config file:

    maxWidth - The maximum width that images will be rendered at (Optional - Leave blank if you do not want a maximum width)

    database - The name of the live DB (ie: web)

    Read more Back
    Code examples

    Solution screenshots(0)


    Reviews (0)

    Sort by: Date Most votes
    • Profile Avatar

      Level: 0

      x0 x0 x0




      Was this helpful?


    Comments (0)

    Sort by: Date  Most votes

    Leave a Comment

    Comment must be field in
    Post comment

    Write a review

    Title can't be empty
    Review can't be empty
    Post review


    Title Description Download Action

    Add File