Images

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.

Example

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:

<script src="https://scripts.sirv.com/sirvjs/v3/sirv.js"></script>
<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg">

Options

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 div or to all instances on the page in a script.

Options in a div

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

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="threshold:400">

Options in a script

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

<script>
  var SirvOptions = {
    lazyImage: {
    threshold: 400
    }
  }
</script>

Threshold

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.

Quality

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:

<script>
  var SirvOptions = {
    lazyImage: {
      quality: 90,
      hdQuality: 80,
    }
  }
</script>

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="https://demo.sirv.com/salad.jpg?q=85" 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

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

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):

<div style="width:600px; height:200px">
  <img data-src="https://demo.sirv.com/tomatoes-basil.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/tomatoes-basil.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/tomatoes-basil.jpg" class="Sirv image-fill" data-options="fit:crop"/>
</div>

Open the images above 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, 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

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.

Fullscreen

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="https://demo.sirv.com/salad.jpg" data-options="fullscreen.always:true" class="Sirv"></div>

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.

Example:

<div data-bg-src="https://demo.sirv.com/image.jpg" 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="https://www.a-website.com/image.jpg" 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