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 using data-options or globally to all instances on the page with a script using the variable SirvOptions (or SirvMobileOptions for mobile devices).

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>

Mobile options

You can set different options for mobile devices with SirvMobileOptions. The example below sets different quality settings for desktop and mobile devices:

<script>
var SirvOptions = {
  viewer: {
    quality: 85,
    hdQuality: 75
  }
}
var SirvMobileOptions = {
  viewer: {
    quality: 70,
    hdQuality: 55
  }
}
</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">

Use placeholder for faster experience

Consider adding a placeholder image for the fastest experience and to improve your PageSpeed Insights score.

Benefits include:

  • Faster appearance of images above the fold.
  • Reduced Total Blocking Time (in combination with Sirv.js async loading).
  • Faster Time to Interactive.
  • Better timing for Largest Contentful Paint.
  • Better timing for Cumulative Layout Shift.

To use a placeholder, add a src attribute to the image, to be shown temporarily while sirv.js calculates the most optimal data-src image for the user. Also add loading="lazy", so that src images below the fold don't load.

The example below will request a src image of 400px width, by applying the scaling option of ?w=400. You can use either w or h to specify the desired width or height:

<img src="https://demo.sirv.com/example.jpg?w=400" data-src="https://demo.sirv.com/example.jpg" class="Sirv">

The placeholder won't show for long, so consider setting lower image quality, to reduce its file size, e.g.

https://demo.sirv.com/example.jpg?w=400&q=30

The placeholder image will appear immediately because it loads as the page loads. Meanwhile, once sirv.js has loaded, it will load the data-src image in the most optimal dimensions. Once loaded, that image will replace the placeholder image.

This placeholder technique means there's an extra image request during load. However, the technique is attactrive because the user gets a fast experience, while also receiving the most optimally scaled image for their device - the best of both worlds.

Was this article helpful?

Get help from a Sirv expert