Responsive imaging

This documentation shows how to easily add responsive images to your websites/apps. For assistance, please contact support from your Sirv account. If you don’t have a Sirv account yet, create your free account now.

Perfectly sized images

Sirv can automatically deliver images to fit your users screen. Whether iPhone, iPad, mobiles, tablets or desktop/laptops, Sirv will detect the available dimensions and create an image to fit.

Sirv does this by resizing your image, caching it and rapidly delivering it to the user. Simple to setup, this is one of the easiest ways for web designers and developers to embed responsive images in web pages.

180px width div
Responsive image demo 1
40% width div
Responsive image demo 2
100% width div
Responsive image demo 3

Interactive example

Drag the slider to change the width of the containing div. Larger images are fetched when the div becomes larger:

350px

233px

Responsive image demo

Setup

To use responsive imaging, follow these two steps:

1. Add class=”Sirv” to your image and use data-src instead of src, for example:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv">

2. Reference the sirv.js file, if it’s not already in your page (it’s the same file used for embedding zooms/spins):

<script src="https://scripts.sirv.com/sirv.js"></script>

Cropped, responsive images

You can add other dynamic image effects to your responsive images. All of Sirv’s 70+ dynamic imaging options are available.

For example, you can create a full width responsive image that is cropped to a certain height (in % or px). The example below is 200px height. While the width will change depending on the size of the users screen, the height will remain the same:

<img data-src="https://demo.sirv.com/Model-X.jpg?h=100%&ch=200&cy=center" class="Sirv" />

This technique is ideal for full-page-width responsive images that you often see on home pages, to give a dramatic first impression.

Lazy loading

To help pages load as fast as possible, for the best user experience, Sirv responsive images automatically use lazy loading. This loading method fetches the image when it is needed, instead of fetching all images on page load. Only images within the viewable part of the page will load. Images out of view will not load unless the user scrolls down the page and they come into view.

To use lazy loading, add a class of Sirv to an image, like so:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" />

The loading effect smoothly fades in the image, giving a discreet feeling. You can adjust the speed or opacity of the effect by adding img.Sirv.sirv-image-loading and img.Sirv.sirv-image-loaded classes to your page. The default settings are:

<style>
  img.Sirv.sirv-image-loading {
    opacity: 0;
  }
  img.Sirv.sirv-image-loaded {
    transition: opacity .4s linear;
    opacity: 1;
  }
</style>

To remove the fade-in effect, apply this style in your HTML page:

<style>
  img.Sirv.sirv-image-loaded {
    transition: none;
  }
</style>

To use lazy loading on an image with fixed width or height (i.e. not a responsive image), set resize to false:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" data-options="resize:false" width="300" />

To disable lazy loading of your responsive images, set lazy to false:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" data-options="lazy:false" />

Lazy loading threshold

Images that are out of sight are lazy-loaded as soon as they enter the viewport (when the user scrolls down the page). This means the user might notice the image loading.

Instead, you can set the threshold to lazy-load the image before it comes into view. This means the image will probably have preloaded by the time the user gets to it (unless they scroll down the page quickly).

This image loads when it gets to within 200px of the viewport edge:

Threshold image demo 1

You can either apply the threshold setting via the data-options tag:

<img data-src="https://demo.sirv.com/spacex-prop-descent2.jpg" class="Sirv" data-options="threshold:200"/>

Or you can use a script, to apply the options to all images on the page:

<script>
    var SirvOptions = {
        image: {
            threshold: 200
        }
    };
</script>

You can also set images to load within a percentage of the viewport height. This example will load all images on the page when they are within 50% of the height of the users viewport:

<script>
    var SirvOptions = {
        image: {
            threshold: '50%' 
        }
    };
</script>

Automatic scale/crop

Sirv can perfectly resize and crop and image to fit a container (e.g. a div). This is a great time-saver when building responsive websites, with images of the most optimal dimensions for each screen size (without serving images larger than needed).

Set the fit option to either contain, cover or crop.

The examples below show a large image (4000 x 2250px) placed in a 600 x 200px div.

contain – scales the image to fit its container, without any cropping (the default behaviour):

<div style="width:600px; height:200px">
<img data-src="https://demo.sirv.com/ecohome.jpg" class="Sirv image-fit"/>
</div>

cover – scales the image to fill its container. The dimensions of the image may differ from the container size, if the image’s aspect ratio does not match the aspect ratio of its container:

<div style="width:600px; height:200px">
<img data-src="https://demo.sirv.com/ecohome.jpg" class="Sirv image-fill" data-options="fit:cover"/>
</div>

crop – scales and crops the image from its center, to fill its container. The size of the delivered image will exactly match the size of the container.

<div style="width:600px; height:200px">
<img data-src="https://demo.sirv.com/ecohome.jpg" class="Sirv image-fill" data-options="fit:crop"/>
</div>

Right-click the images above and open them in a new tab to see their actual sizes. The cover image uses the original aspect ratio, with no cropping, with part of the image hidden; the crop image has been cropped by Sirv to the desired dimensions.

To display the images without stretching them, you should also add the following CSS styles to your page or external CSS file:

<style>
    img.Sirv {
        width: 100%;
        height: 100%;
    }
    img.Sirv.image-fit,
    img.Sirv.image-fill {
        width: 100%;
        height: 100%;
    }

    img.Sirv.image-fit {
        object-fit: contain;
    }

    img.Sirv.image-fill {
        object-fit: cover;
    }
</style>

Resize step

For better user experience, when a user resizes their browser, new images are only served if the difference in image size is at least 50px. This helps keep your page feeling fast.

The resize step can be increased to a higher value or reduced as low as 10px. To change the value, use the resizeStep option:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" data-options="resizeStep: 100;">

Retina images

Sirv responsive imaging supports HiDPI (retina) images, to serve beautifully sharp images to retina devices. Retina images have incredible clarity but are roughly 4 times larger in file size. For faster image downloading, you can turn off retina and Sirv will deliver 72dpi images instead.

To turn off retina images, set retina to false:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" data-options="retina:false">

Faster initialization

To load images faster, you can prefetch the DNS and pre-initiate the connection to Sirv resources.

Paste the code below between the <head> and </head> of your HTML page:

<link rel="preconnect" href="https://scripts.sirv.com" crossorigin/>
<link rel="preconnect" href="YOUR-SIRV-URL" crossorigin/>
<link rel="dns-prefetch" href="https://scripts.sirv.com"/>
<link rel="dns-prefetch" href="YOUR-SIRV-URL"/>

In the code, change YOUR-SIRV-URL to match your Sirv subdomain e.g. https://youraccount-cdn.sirv.com or https://youraccount.sirv.com.

This technique typically loads sirv.js 100-300 ms sooner, for browsers that support preconnect. For browsers that only support DNS prefetch, it loads 10-150 ms sooner. You can measure the time taken for DNS lookup, initial connection and SSL handshake with your browser console. In Chrome, it looks like this:

Chrome waterfall inspector - connection analysis

Options

Table of options that can be applied via the ‘data-options’ tag:

Parameter Default Options Description
retina true true / false Load retina images on HiDPI screens
resize true true / false Enable responsiveness when page is resized
resizeStep 50 numeric Width threshold to fetch new image when window resized (minimum 10px)
lazy false true / false Enable lazy loading of images as they come into view
threshold 0px px / % / crop Distance from viewport edge before lazy loading is triggered
fit contain contain / cover / crop Hide or crop image if it is larger than the container

Options can alternatively be applied to all images on the page by using a script tag:

<script>
  var SirvOptions = {
    image: {
      retina: false
    }
  };
</script>

or like this:

<script>
  var SirvOptions = {};
  SirvOptions.image = {
    retina: false
  };
</script>

API

Responsive images will automatically initialize when the DOM is ready.

Alternatively, you can control images with these commands:

  • Sirv.start() – starts all instances of .Sirv on the page.
  • Sirv.stop() – stops all instances of .Sirv on the page.

To control a particular image on the page, specify its #id:

  • Sirv.start(<#id>) – starts the .Sirv instance with a specific #id.
  • Sirv.stop(<#id>) – stops the .Sirv instance with a specific #id.

For example, you can prevent automatic loading by setting “autostart” to false:

<script>
  var SirvOptions = {
    autostart: false
  };
</script>

Once the page has loaded, you can start Sirv on a specific element, such as this image:

<img data-src="https://demo.sirv.com/Model-X.jpg" class="Sirv" id="sirv-image">

Start it by #id:

<script>
    Sirv.start('sirv-image');
</script>

Start it by DOM Node:

<script>
    var sirvImage = document.querySelector('.Sirv');
    Sirv.start(sirvImage);
</script>

If you use Sirv Spin, refer to the wide range of Sirv Spin API methods.

Was this article helpful?