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:

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

Add Sirv JS to your page, preferably as early as possible in your code, before any other scripts:

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

Options

You can control when and how images load:

Parameter Default Options Description
autostart visible created, visible, off Automatically initiate the image viewer (lazy loading).
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.
resize true true, false Load resized image if viewport changes size.

How to apply options

Options can be applied either inline to an img with the parameter data-options or globally to all instances on the page via a script with the variable SirvOptions.

Inline and script examples are provided below. Only one of the approaches is needed. If both approaches are used, the inline option will take precedence.

Autostart & lazy loading

autostart defines when content starts loading. There are 3 possible values:

  • visible (default) - loading starts when image enters viewport (lazy loading).
  • created - loading starts when image src is created (earliest load).
  • off - loading should be started via the API.

Lazy loading is applied by default, when the image becomes visible in the viewport. Instead, you can choose created to disable lazy loading and load the image as soon as sirv.js has calculated the most optimally sized image, like so:

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="autostart:created">
<script>
var SirvOptions = {
  lazyImage: {
    autostart: 'created'
  }
}
</script>

Threshold

threshold can prevent delays when loading a lazy load. By default, as a user scrolls down your page, an image will lazy load once it enters the viewport (i.e. the visible part of the page). Instead, you can commence lazy loading once the user is within a certain distance of the viewport.

This example will load the image once it's within 200px of the viewport:

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="threshold:200">
<script>
var SirvOptions = {
  lazyImage: {
    threshold: 200
  }
}
</script>

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:

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="quality:90;hdQuality:80">
<script>
var SirvOptions = {
  lazyImage: {
    quality: 90,
    hdQuality: 80,
  }
}
</script>
<img data-src="https://demo.sirv.com/salad.jpg?q=85" class="Sirv">

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

Retina delivery

Retina (HD) quality is applied if:

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

Retina images are always served to HD screens, this cannot be disabled.

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.

Set it to contain to scale the image to fit its container, without any cropping (the default behaviour):

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="fit:contain">
<script>
var SirvOptions = {
  lazyImage: {
    fit: 'contain'
  }
}
</script>

Set it to cover to scale 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="https://demo.sirv.com/tomatoes-basil.jpg" class="Sirv image-fill" data-options="fit:cover">
<script>
var SirvOptions = {
  lazyImage: {
    fit: 'cover'
  }
}
</script>

Set it to crop to scale and crop 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="https://demo.sirv.com/tomatoes-basil.jpg" class="Sirv image-fill" data-options="fit:crop">
<script>
var SirvOptions = {
  lazyImage: {
    fit: 'crop'
  }
}
</script>

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.

Resize

The resize parameter fetches a freshly scaled 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.

If you'd like to disable this, set resize to false:

<img class="Sirv" data-src="https://demo.sirv.com/tomatoes-basil.jpg" data-options="resize:false">
<script>
var SirvOptions = {
  lazyImage: {
    resize: false
  }
}
</script>

Fullscreen

You can make the image expand to fullscreen on click, with the fullscreen.always parameter (one Sirv Media Viewer's global options). Instead of an img tag, use a div tag and apply your settings in data-options, for example:

<div data-src="https://demo.sirv.com/salad.jpg" data-options="fullscreen.always:true" class="Sirv"></div>
<script>
var SirvOptions = {
  viewer: {
    fullscreen: {
      always: true
    }
  }
}
</script>

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

Sirv Media Viewer can lazy load assets that are not hosted on Sirv. If you do this, apply the attribute data-type="static" so that it bypasses dynamic scaling, to load the asset sooner. 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

Add height to prevent CLS

If your content jumps during image loading, that is known as CLS (Cumulative Layout Shift). To prevent this, you can either add height to the container around your image or you can add height (and width) to your images. Simply add height and width parameters, for example:

<img data-src="https://demo.sirv.com/example.jpg" class="Sirv" width="620" height="413">

Was this article helpful?

Get help from a Sirv expert