On this page

Responsive, lazy loading images

Sirv Media Viewer is a powerful tool for serving the most optimal images to your website.

Web development best practices recommend serving scaled and lazy loaded images. That means each image should be scaled to the appropriate size for each visitor (not scaled in the browser) and loaded only if required (lazily). Sirv Media Viewer automatically performs both dynamic resizing and lazy loading.


The following image is automatically scaled to fit the viewport. It loads lazily, on-demand:

This is achieved by giving the img a class and data-src like so:

<img class="Sirv" data-src="">

Don't forget to include Sirv JS (insert it before </head>or </body> tags.)

<script src=""></script>

Sirv JS is modular, if you're not using 360 spins or image zoom, you might want to include only the lazy image component. You can do it like this:

<script src="" data-components="image"></script> 


You can control when and how images load:

Parameter Default Options Description
threshold 0 number (px) Distance from viewport before loading is triggered.
quality 80 0-100 (%) Quality of standard images.
hdQuality 60 0-100 (%) Quality of hi-res images (retina).
fit contain contain, cover, crop Method to scale/crop image to fit area.
autostart visible created, visible, off Automatically initiate the image viewer.
resize true true, false Load resized image if viewport changes size.

Applying options

Options can be applied either in the img or to all instances on the page in a script.

Options in an img tag

Use the data-options tag to apply options in the img, for example:

<img class="Sirv" data-src="" data-options="threshold:400">

Options in a script

Options applied in a script will be applied to all Sirv images on the page:

var SirvOptions = {
  lazyImage: {
    threshold: 400


threshold helps you avoid any delay when images load. As a visitor scrolls down your page, an image starts loading as soon as part of it comes into the viewport (the users screen). Instead, you can load it earlier, so that it has either fully loaded or started loading when the user gets to it, for example, when the image gets within 200px of the viewport.


The following image quality defaults are applied to JPEG/WebP images:

  • Standard images: 80%
  • Hi-res images: 60% (retina screens)

Change image quality with the quality and hdQuality parameters.

For example, raise the quality to 90% and 80% like so:

<img class="Sirv" data-src="" data-options="quality:90;hdQuality:80">
var SirvOptions = {
  lazyImage: {
    quality: 90,
    hdQuality: 80,

Quality can also be applied to an image via its URL. Quality in the URL will supersede any other quality settings.

Append the q parameter in a query string like so:

<img data-src="" class="Sirv">

If the quality parameter is in the URL and its value is lower than the hdQuality setting, the URL parameter will supersede the hdQuality setting.

HD quality is applied if:

  • Device pixel ratio (DPR) >= 1.5
  • Image can be loaded at >=1.5x size of its viewport size


autostart defines when Sirv Media Viewer starts. There are 3 options:

  • created - the viewer will start automatically when its instance is created.
  • visible - the viewer will start automatically when it becomes visible in the viewport.
  • off - the viewer will not start automatically. It can be started manually via the API.


fit lets you crop an image as well as resize it.

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

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

<img class="Sirv" data-src="" data-options="fit:contain">
var SirvOptions = {
  lazyImage: {
    fit: contain

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:

<img data-src="" class="Sirv image-fill" data-options="fit:cover"/>
var SirvOptions = {
  lazyImage: {
    fit: cover

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.

<img data-src="" class="Sirv image-fill" data-options="fit:crop"/>
var SirvOptions = {
  lazyImage: {
    fit: crop

The last 2 images above look the same but are different. Open them in a new tab and you'll see that cover uses the original aspect ratio while crop has been cropped to the desired dimensions.


The resize parameter will fetch a newly resized image if the viewport is resized. This could happen when rotating from portrait to landscape on a mobile - the viewport will become much wider, so Sirv will load a larger version of the image.

To disable this, change resize to false.


You can make the image expandable to fullscreen on click with the fullscreen.always parameter (from the general options). Instead of an img tag, use a div tag and apply the options in data-options, like so:

<div data-src="" data-options="fullscreen.always:true" class="Sirv"></div>
var SirvOptions = {
  viewer: {
    fullscreen: {
      always: true

Lazy loading background images

You can also apply responsive scaling and lazy loading to background images:

1. Create a div with a class of Sirv (note it should not be an img).

2. Provide the image URL in the data-bg-src attribute.


<div data-bg-src="" class="Sirv"></div>

Lazy loading external assets

You can also use Sirv Media Viewer to lazy load assets not hosted on Sirv. If you do this, apply the attribute data-type="static" and it will help the asset load much faster. For example:

<img data-src="" class="Sirv" data-type="static">

Custom 404

If an image is missing, a 404 error is returned. You can customize this to serve an image of your choice.

Set a custom error message in your Default profile or set a custom error message to a specific set of images via another profile. Go to your Profiles page to choose the profile, click Edit and in General Settings enter the path to your image in the "Default image" field.

Example custom image, shown instead of an empty 404 error:

No such image

Was this article helpful?

Get help from a Sirv expert