Sirv Media Viewer
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>
Selectively load compontents
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>
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/example.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> </div>
<script> var SirvOptions = { viewer: { threshold: 200 } } </script>
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> </div>
<script> var SirvOptions = { viewer: { arrows: false } } </script>
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> </div>
<script> var SirvOptions = { viewer: { orientation: 'vertical' } } </script>
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> </div>
<script> var SirvOptions = { viewer: { loop: false } } </script>
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> </div>
<script> var SirvOptions = { viewer: { autostart: 'off' } } </script>
Thumbnails
Thumbnails under the gallery allow swapping between assets.
Thumbnail layout
The layout can be changed by setting thumbnails.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> </div>
<script> var SirvOptions = { viewer: { thumbnails: { type: 'bullets' } } } </script>
Thumbnail position
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> <div data-src="https://demo.sirv.com/demo/apt/03.jpg" data-type="zoom"></div> <div data-src="https://demo.sirv.com/demo/apt/04.jpg" data-type="zoom"></div> <div data-src="https://demo.sirv.com/demo/apt/05.jpg" data-type="zoom"></div> <div data-src="https://demo.sirv.com/demo/apt/06.jpg" data-type="zoom"></div> </div>
<script> var SirvOptions = { viewer: { thumbnails: { position: 'left' } } } </script>
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> </div>
<script> var SirvOptions = { viewer: { thumbnails: { size: 110 } } } </script>
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>
<script> var SirvOptions = { viewer: { thumbnails: { enable: false } } } </script>
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>
<script> var SirvOptions = { viewer: { slide: { animation: { type: 'slide' } } } } </script>
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>
<script> var SirvOptions = { viewer: { slide: { animation: { duration: 500 } } } } </script>
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>
<script> var SirvOptions = { viewer: { thumbnails: { enable: false }, slide: { autoplay: true, delay: 2000 } } } </script>
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>
<script> var SirvOptions = { viewer: { slide: { first: 2 } } } </script>
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>
<script> var SirvOptions = { viewer: { slide: { preload: false } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen: { always: true } } } </script>
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-shadow.jpg" data-type="zoom"></div> </div>
<script> var SirvOptions = { viewer: { fullscreen: { native: true } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen: { enable: false } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen: { thumbnails: { size: 150 } } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen: { thumbnails: { position: 'left' } } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen: { thumbnails: { type: 'left' } } } } </script>
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>
<script> var SirvOptions = { viewer: { fullscreen:{ thumbnails: { autohide: true } } } } </script>
To remove thumbnails from fullscreen view, set fullscreen.thumbnails.enable to false:
<div class="Sirv" data-options="fullscreen.thumbnails.enable:false"> <div data-src="https://demo.sirv.com/demo/apt/01.jpg"></div> </div>
<script> var SirvOptions = { viewer: { fullscreen:{ thumbnails:{ enable: false } } } } </script>
Fullscreen icon
A variety of fullscreen icons are available:
The icons are numbered from 01 to 18. Apply one of the icons by adding some CSS to your web page, like so:
<style> .smv-button-fullscreen-open .smv-icon { -webkit-mask-image: url(https://scripts.sirv.com/sirvjs/v3/graphics/buttons/fullscreen.07.svg) !important; } </style>
Alternatively, you could design your own square SVG (or PNG) icon and apply it with CSS, like so:
<style> .smv-button-fullscreen-open .smv-icon { -webkit-mask-image: url(https://your-account.sirv.com/icons/your-new-icon.svg) !important; } </style>
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/example.spin"></div> </div>
<script> var SirvOptions = { viewer: { contextmenu: { enable: true } } } </script>
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/example.spin"></div> </div>
<script> var SirvOptions = { viewer: { contextmenu: { enable: true, text: { zoom: { in: 'Click here to zoom' } } } } } </script>
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>
Alt text
alt tags are added to images/spins if a description has been added to the asset in Sirv.

Alternatively, alt tags can be added via the data-alt attribute, for example:
<div class="Sirv"> <div data-src="https://demo.sirv.com/example.spin" data-alt="Alt tag on spin"></div> <div data-src="https://demo.sirv.com/example.jpg" data-alt="Alt tag on zoomable image" data-effect="zoom"></div> </div>
For accessibility, spins also have the additional attributes role="img" and aria-label="<alt text goes here>" added to the <canvas>.
Faster initialization
To load images faster, you can do 3 things:
- Pre-fetch and preconnect
- Use sirv.full.js
- Move sirv.full.js to the head
Pre-fetch and preconnect
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 or WordPress CDN plugin).
Paste the following code between the <head> and </head> of your HTML page:
<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">
Replace your-sirv-account with your Sirv account name or if you use a custom domain, replace your-sirv-account.sirv.com with your custom domain.
Prefetching and preconnect can load files 100-300 ms sooner, for browsers that support preconnect. For browsers that only support DNS prefetch, files can load 10-150 ms sooner.
Use sirv.full.js
By default, sirv.js will load the least possible JS code, then request each of the Sirv JS components (image, zoom, 360 spin, video). Instead, you can either specify which components to load or you can load all the components in a single sirv.full.js request:
<script src="https://scripts.sirv.com/sirvjs/v3/sirv.full.js"></script>
Replacing sirv.js with the larger sirv.full.js avoids making additional Sirv JS calls, therefore allowing scaled images to be requested sooner. This could load images 50-1000 ms sooner, depending on your page.
Move JS to the head
In case your sirv.js or sirv.full.js file is somewhere near the end of your page, move it up into the head, somewhere before the </head> tag.
This could load images 100-2000 ms sooner, especially if your page references many other JavaScript files.
Credit
Special thanks to Gravity 360 for the beautiful product imagery of the Snug Shack sofa.