Sirv Media Viewer

On this page

About

Sirv Media Viewer is a highly advanced viewer for images, videos and 360 spins. It intelligently resizes assets to suit each users screen and lazy loads the assets from Sirv's CDN. Use it to serve one asset or multiple assets with thumbnails.

Example with zoomable images, 360 spin and video:

Usage

It's easy to embed Sirv Media Viewer in your page.

1. Copy and paste this script anywhere in your HTML, usually before the </head> or the </body>:

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

2. Add a div with class of "Sirv", containing more divs for each of your assets. This example contains one spin, one zoomable image and one video:

<div class="Sirv">
  <div data-src="https://demo.sirv.com/example.spin"></div>
  <div data-src="https://demo.sirv.com/image.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/video.mp4"></div>
</div>

Options

Adjust the style with over 30 options below, plus zoom, spin, video and responsive image options.

Parameter Default Options Description
quality 80 0-100 (%) Quality of standard images.
hdQuality 60 0-100 (%) Quality of hi-res images (retina).
threshold 0 numeric (px) Distance below viewport when responsive images should load.
arrows true true, false Display arrows to the left/right of the image.
orientation horizontal horizontal, vertical Position of arrows.
loop true true, false Loop from the last image to the first image.
autostart visible visible, created, off When to load images.
Thumbnails
thumbnails.enable true true, false Display thumbnail for each item.
thumbnails.size 70 numeric (px) Thumbnail height/width.
thumbnails.position bottom bottom, top, left, right Thumbnail location, relative to main image.
thumbnails.type square square, auto, bullets, grid Style of thumbnails.
thumbnails.target false true, false Trigger thumbnail from query selector.
Slider
slide.animation.type fade fade, slide, off Style of animation.
slide.animation.duration 200 numeric (ms) Duration of animation effect.
slide.autoplay false true, false Automatically slide the images in a slideshow.
slide.delay 3000 numeric (ms) Time between each autoslide.
slide.first 0 numeric First slide to play (from 0 upwards).
slide.preload true true, false Preload the images, to remove any loading delay.
Fullscreen
fullscreen.always false true, false Go immediately to fullscreen on click.
fullscreen.native false true, false Use entire fullscreen instead of page fullscreen.
fullscreen.enable true true, false Enable option to go fullscreen.
fullscreen.thumbnails.size auto auto or number (px) Dimensions of fullscreen thumbnails.
fullscreen.thumbnails.position bottom bottom, top, left, right Location of fullscreen thumbnails.
fullscreen.thumbnails.type square square, auto, bullets Style of fullscreen buttons.
fullscreen.thumbnails.autohide false true, false Hide the thumbnails discreetly.
fullscreen.thumbnails.enable true true, false Show thumbnails in fullscreen mode.
Context menu
contextmenu.enable false true, false Enable the context menu on right-click.
contextmenu.text.zoom.in Zoom in Change the text for zoom in.
contextmenu.text.zoom.out Zoom out Change the text for zoom out.
contextmenu.text.fullscreen.enter Enter Full Screen Change the text to enter fullscreen.
contextmenu.text.fullscreen.exit Exit Full Screen Change the text to exit fullscreen.
contextmenu.text.download Download image Change the text for download.

Applying options

Options can be applied to each image individually (div) or to all instances on the page (script).

Options in a div

Use the data-options tag to apply options in the relevant div. There is a containing div for the viewer, then a div for each asset (image, video or spin):

<div class="Sirv" data-options="fullscreen.enable:false;">
  <div data-src="https://demo.sirv.com/360.spin" data-options="inactivity:7000;"></div>
  <div data-src="https://demo.sirv.com/image.jpg" data-type="zoom" data-options="mode:right;"></div>
  <div data-src="https://demo.sirv.com/video.mp4" data-options="autoplay:true;"></div>
</div>

Options in a script

To apply options to every instance in your page or site, use a script, for example:

<script>
  var SirvOptions = {
    viewer: {
      spin: {
        inactivity: '7000',
      },
      zoom: {
        mode: 'right',
      },
      video: {
        autoplay: true,
      }
    }
  }
</script>

Quality

Images in Sirv Media Viewer use the following quality by default:

  • quality - 80% for standard images
  • hdQuality - 60% for hi-res images (retina screens)

Adjust the image quality with the quality and hdQuality parameters. For example, raise the quality to 90% and 80% like so:

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

Or set it inline, like so:

<div class="Sirv" data-options="quality:90; hdQuality:80">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Threshold

Images are lazy-loaded, meaning that they only load if and when they come into view. You can load them slightly earlier, when they reach a certain distance from the viewport, by setting threshold to a value. This will load the images 200px before they enter the viewport:

<div class="Sirv" data-options="threshold:200">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Arrows

Arrows appear to the left and right, to move to the next/previous image. They can be disabled by setting the arrows parameter to false:

Arrows on hover:

No arrows:

The code looks like this:

<div class="Sirv" data-options="arrows:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Orientation

Arrows appear left and right by default. Instead, they can be shown top and bottom, by setting orientation to vertical:

Horizontal:

Vertical:

The code looks like this:

<div class="Sirv" data-options="orientation:vertical">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Loop

The slider will continue to the first image after showing the last image. This can be stopped by setting the loop parameter to false:

Loop:

No loop:

The code looks like this:

<div class="Sirv" data-options="loop:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Autostart

The images lazy load by default, when they enter the viewport. This avoids unnecessary data transfer, loading images further down the page that aren't needed.

  • visible - images lazy load when they enter the viewport.
  • created - images load immediately (on page load or upon API creation).
  • off - images don't load until you start them with the API.
<div class="Sirv" data-options="autostart:off">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Thumbnails

Thumbnails under the gallery allow swapping between assets.

Thumbnail layout

The layout can be changed by setting thumbnail.type to any of these options:

  • square - Square thumbnails
  • auto - Original aspect ratio thumbnails
  • bullets - Bulleted dots
  • grid - Wrapped rows of thumbnails

Square:

Auto:

Bullets:

Grid:

The code looks like this:

<div class="Sirv" data-options="thumbnails.type:bullets">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Thumbnails are shown underneath by default. They can be moved to the left, right or top with the thumbnails.position parameter:

<div class="Sirv" data-options="thumbnails.position:left">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Thumbnails are sized automatically. Instead, you can set a size in px with the thumbnails.size parameter. This will set thumbnails with 110px height:

<div class="Sirv" data-options="thumbnails.size:110">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg" data-type="zoom"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg" data-type="zoom"></div>
  etc.
</div>

Disable thumbnails

Thumbnails can be removed by setting thumbnails.enable to false:

<div class="Sirv" data-options="thumbnails.enable:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Custom thumbnails

You can show a completely different thumbnail of your choice by applying the data-thumbnail-image attribute. For example:

<div class="Sirv">
  <img data-src="https://demo.sirv.com/example.jpg" data-thumbnail-image="https://demo.sirv.com/thumbnail-of-your-choice.jpg">
</div>

Slider

Adjust how the main image animates between slides.

Slide animation

This animation style can be set to slide.animation.type to fade, slide or off. Off changes the image instantly:

Fade (default):

Slide:

Off:

<div class="Sirv" data-options="slide.animation.type:slide">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

The animation speed can be changed by adjusting slide.animation.duration:

100 ms:

200 ms (default):

500 ms:

<div class="Sirv" data-options="slide.animation.duration:500">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Slide autoplay

The slider can automatically move from one image to the next. Set slide.autoplay to true:

Disable the thumbnails with thumbnails.enable:false and it becomes a slideshow:

Adjust the time each slide shows by setting slide.delay to a longer or shorter duration:

2000 ms:

5000 ms:

<div class="Sirv" data-options="thumbnails.enable:false; slide.autoplay:true; slide.delay:2000">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

First slide

Change the first image to be shown. It is 0 by default (for the first image). Change slide.first to another value:

<div class="Sirv" data-options="slide.first:2">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Preload slides

The slides will preload, so that there is no delay in showing other images. You can disable this by setting slide.preload to false:

<div class="Sirv" data-options="slide.preload:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Fullscreen

A fullscreen icon in the top right permits big, detailed images.

Instant fullscreen

To instantly launch fullscreen on click, set fullscreen.always to true:

<div class="Sirv" data-options="fullscreen.always:true">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
</div>

Fullscreen size

There are two types of fullscreen:

  • Viewport - within the browser window.
  • Native - the entire screen.

The viewport is used by default. To use native fullscreen, set fullscreen.native to true:

<div class="Sirv" data-options="fullscreen.native:true">
<div data-src="https://demo.sirv.com/demo/snug/pink-w.jpg" data-type="zoom"></div>
</div>

Viewport

Native

Disable fullscreen

To disable fullscreen and hide the button, set fullscreen.enable to false:

<div class="Sirv" data-options="fullscreen.enable:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Fullscreen thumbnails

Thumbnails in fullscreen will be automatically sized. Instead, you can set a specific size in px with the fullscreen.thumbnails.size parameter. This will set 150px:

<div class="Sirv" data-options="fullscreen.thumbnails.size:150">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

150px

80

Thumbnails are shown to the bottom by default. Instead, they can be shown to the top, left or right with the fullscreen.thumbnails.position parameter:

<div class="Sirv" data-options="fullscreen.thumbnails.position:left">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Left

Top

Right

Fullscreen thumbnails are square by default. You can change the style by setting fullscreen.thumbnails.type to any of these options:

  • square - Square thumbnails
  • auto - Original aspect ratio thumbnails
  • bullets - Bulleted dots
<div class="Sirv" data-options="fullscreen.thumbnails.type:left">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

Square

Auto

Bullets

To hide the thumbnails until the user moves their mouse down, set fullscreen.thumbnails.autohide to true:

<div class="Sirv" data-options="fullscreen.thumbnails.autohide:true">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/02.jpg"></div>
  <div data-src="https://demo.sirv.com/demo/apt/03.jpg"></div>
</div>

To remove thumbnails from fullscreen view, use fullscreen.thumbnails.enable:

<div class="Sirv" data-options="fullscreen.thumbnails.enable:false">
  <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div>
</div>

Context menu

The right-click context menu is disabled by default. Enable it by setting contextmenu.enable tag to true:

<div class="Sirv" data-options="contextmenu.enable:true;">
  <div data-src="https://demo.sirv.com/360.spin"></div>
</div>

To change any text in the context menu, apply these parameters:

  • contextmenu.text.zoom.in - text for zooming in
  • contextmenu.text.zoom.out - text for zooming out
  • contextmenu.text.fullscreen.enter - text for going into fullscreen
  • contextmenu.text.fullscreen.exit - text for leaving fullscreen
  • contextmenu.text.download - text for downloading the image
<div class="Sirv" data-options="contextmenu.enable:true; contextmenu.text.zoom.in:Click here to zoom">
  <div data-src="https://demo.sirv.com/360.spin"></div>
</div>

Mobile settings

To set different settings for mobile devices, use one of three ways to apply options. The examples below change the spin hint message to "Tap then drag".

Use a script to apply the settings to all instances on a page:

<script>
  var SirvMobileOptions = {
    viewer: {
      spin: {
        hint: {
          message: {
            text: 'Tap then drag'
          }
        }
      }
    }
  }
</script>

Alternatively, apply inline settings to Sirv Media Viewer:

<div data-src="https://demo.sirv.com/example.spin" class="Sirv" data-mobile-options="spin.hint.message.text: Tap then drag"></div>

Or apply inline settings to a specific item inside the viewer:

<div class="Sirv">
  <div data-src="https://demo.sirv.com/example.spin" data-mobile-options="hint.message.text: Tap then drag"></div>
</div>

Additional attributes

The data-id attribute can be used to set a unique item name. The name can then be used to control the item via the API. For example this sets an id of my-item to the second image:

<div class="Sirv">
    <div data-src="https://demo.sirv.com/ian.jpg"></div>
    <div data-src="https://demo.sirv.com/jump.jpg" data-id="my-item"></div>
    <div data-src="https://demo.sirv.com/kitesurf.jpg"></div>
</div>

Then controlled va the API:

Sirv.on('viewer:ready', (viewer) => {
    let myslide = viewer.child('my-item');
});

The data-disabled attribute can exclude an item from the viewer. Disabled items can be included again via the API. Disabled items are not initilialized until enabled. For example:

<div class="Sirv" id="my-viewer">
    <div data-src="https://demo.sirv.com/ian.jpg"></div>
    <div data-src="https://demo.sirv.com/jump.jpg" data-id="my-item" data-disabled></div>
    <div data-src="https://demo.sirv.com/kitesurf.jpg"></div>
</div>

Then enabled by the API:

Sirv.viewer.getInstance('#my-viewer').enableItem('my-item');

Custom styling

You can modify Sirv Media Viewer's appearance by creating your own CSS styles.

Cursor

By default, the native browser cursors are shown on hover over an image, to indicate if an image can be zoomed or dragged. These cursors can be changed or removed by editing the following CSS classes:

<style>
.smv-cursor-zoom-in {
  cursor: zoom-in;
}

.smv-cursor-zoom-out {
  cursor: zoom-out;
}

.smv-cursor-dragging {
  cursor: move;
}
</style>

Lighter versions of sirv.js

The sirv.js library contains all the components of Sirv Media Viewer, making it 283 KB in size, which is served gzipped to 79 KB.

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

Instead of loading everything, you can serve smaller versions of sirv.js, to reduce bandwidth and load your page a few milliseconds faster. These 4 components of sirv.js can be explicitly loaded:

  • Image (lazy loading, responsive images)
  • Spin
  • Zoom
  • Video

To explicitly choose which components to load, list the components in the data-components attribute of the script tag. The example below will load Image and Spin components only:

<script src="https://scripts.sirv.com/sirvjs/v3/sirv.js" data-components="image, spin"></script>

Faster initialization

To load images faster, you can prefetch the DNS and pre-initiate the connection to Sirv resources. This best practice recommendation accelerates page loading and is automatically applied if you're using a Sirv plugin (Magento CDN extension, PrestaShop CDN addon and WordPress CDN plugin).

Paste the code below between the <head> and </head> of your HTML page. Replace your-sirv-account with your Sirv account name. If you use a custom domain, replace your-sirv-account.sirv.com with your custom domain:

<link rel="preconnect" href="https://scripts.sirv.com" crossorigin>
<link rel="preconnect" href="https://your-sirv-account.sirv.com" crossorigin>
<link rel="dns-prefetch" href="https://scripts.sirv.com">
<link rel="dns-prefetch" href="//your-sirv-account.sirv.com">

This technique typically loads files 100-300 ms sooner, for browsers that support preconnect. For browsers that only support DNS prefetch, it loads 10-150 ms sooner.

Credit

Special thanks to Gravity 360 for the beautiful product imagery of the Snug Shack sofa.

Was this article helpful?

Get help from a Sirv expert

Contact Us