Sirv Zoom documentation

This documentation explains how to embed image zoom in your websites/apps.

Zoom & Pan

Sirv Zoom lets you rapidly zoom into huge images. It works like Google Maps – click the image to zoom-in, one level at a time. You can also use the mousewheel or double-tap on a touch device.

Demo with single image

Image zoom demo

By slicing your image into thousands of small image tiles, Sirv is able to zoom deep into images incredibly fast.

Images can be zoomed upon:

  • Single-click / double-click
  • Mousewheel
  • Double-tap (on touchscreens)

Demo with multiple images

Sirv Zoom can auto-generate thumbnails for other images, allowing you to swap between lots of images.

The example below has 3 zoomable images. Every image was created automatically by Sirv from the original large images that were uploaded.

Zoomable image 1
Zoomable image 2
Zoomable image 3

How to create a Zoom

Any image that you upload to Sirv is instantly ready to be zoomed.

Go to an image in your Sirv account and click the Sirv Zoom option. It’ll show you the embed code for your page.

1. Paste the code for the sirv.js file, before the </head> of your web page (or elsewhere on your page):

<script src=""></script>

2. Paste the code for your zoom image wherever you want it to appear on your page, using the <div> embed code shown in your account. It looks like this:

<div class="Sirv" data-effect="zoom" data-src=""></div>

Alternatively, you can embed a zoom using <figure>, for example:

<figure class="Sirv" data-effect="zoom" data-src=""></figure>

Instead of using the data-src attribute to specify the image source, you can use <img> as a nested tag, for example:

<figure class="Sirv" data-effect="zoom">
  <img data-src="" />

Multiple zoom images can be configured in nested <img> tags, like so:

<figure class="Sirv" data-effect="zoom">
  <img data-src=""/>
  <img data-src=""/>
  <img data-src=""/>
  <img data-src=""/>

Alternatively, place the main image in a data-src attribute and additional images in nested <img> tags:

<figure class="Sirv" data-effect="zoom" data-src="" >
  <img data-src=""/>
  <img data-src=""/>
  <img data-src=""/>

Zoom options

zoom-on-wheeltruetrue / falseZoom In/Out on mouse wheel.
fullscreentruetrue / falseEnable or disable the fullscreen view.
fullscreen-onlyfalsetrue / falseGo immediately to full-screen on click.
retinatruetrue / falseEnable/disable retina images.
click-to-zoom10 / 1 / 2Number of clicks to zoom in (0 = disabled)
thumbnailsbottombottom / left / right / #idThumbnail position (use #id to put them elsewhere).
thumbnails-orientationhorizontalhorizontal / verticalThumbnail orientation, if positioned elsewhere with #id.
squareThumbnailstruetrue / falseEnable or disable square thumbnails.
contextmenutruetrue / falseEnable/disable context menu (right-click).
mapfalsetrue / falseEnable/disable the navigation map.
mapSize1-10025Size of the navigation map in percent.
textZoomInZoom Inany textContext menu text for zoom-in.
textZoomOutZoom Outany textContext menu text for zoom-out.
textEnterFullscreenEnter Full Screenany textContext menu text to enter fullscreen.
textExitFullscreenExit Full Screenany textContext menu text to exit fullscreen.
textDownloadDownload Imageany textContext menu text to download the image.

Options can be applied individually or globally.

To apply options individually to a specific zoom, place your options inside the data-options attribute, for example this would disable the mousewheel and align the thumbnails right:

<div class="Sirv" data-effect="zoom" data-options="zoom-on-wheel:false; thumbnails:right"><img data-src="" /></div>

To apply options globally to all your spins, place your options inside a script tag on your page, for example:

  var SirvOptions = {
    zoom: {
      zoom-on-wheel: false,
      thumbnails: "right"

or use:

  var SirvOptions = {};
  SirvOptions.zoom = {
    zoom-on-wheel: false,
    thumbnails: "right"


To disable the mousewheel from zooming into the image, set the zoom-on-wheel option to false:

<div class="Sirv" data-effect="zoom" data-options="zoom-on-wheel:false"><img data-src="" /></div>


Images look even more impressive in full-screen. To enter full-screen, click the button located in the top-right of the zoom. See below on how to customize buttons.

You may like to make full-screen the default user experience. Set the “fullscreen” parameter to “true” and when the user clicks anywhere on the image, full-screen will open, like so:

<div class="Sirv" data-options="fullscreen-only:true"><img data-src="" /></div>

In the bottom right corner, a magnifier icon and “Enlarge” text is shown.

The location of the message can be changed by adding the following CSS to the page and changing the left/right/top/bottom properties as you wish:

  .sirv-zoom-figure-view.fullscreen-only .sirv-zoom-button-fullscreen > span:after {
    right: 12px;
    bottom: 12px;
    top: auto;
    left: auto;

The magnifier and text can be removed by adding this CSS rule to your page:

  .sirv-zoom-figure-view.fullscreen-only .sirv-zoom-button-fullscreen > span {
    display: none !important;

Navigation map

A small version of the image can be shown in the corner of the image, marking the position of the total image that is currently in view. This makes it easier to navigate around very large images.

The map automatically appears when the user zooms in:

Full-screen image zoom demo

The map is off by default. Enable it by setting the map parameter to true:

<div class="Sirv" data-options="map: true;"><img data-src="" /></div>

The map size is defined as a percentage of the image and can be adjusted with the mapSize parameter. The default is 25. This example increases it to 35%:

<div class="Sirv" data-options="map: true; mapSize: 35;"><img data-src="" /></div>
Full-screen image zoom demo

The map is automatically disabled on smartphones because the small screen would make it too intricate to navigate.


You can change the location of the thumbnails to left, right, bottom or somewhere completely different on your page. The default location is bottom, which places image thumbnails under the main image. To change it, set the thumbnails option to left, like so:

<div class="Sirv" data-options="thumbnails:left"><img data-src="" /></div>

You can also change the orientation for thumbnails to be vertical or horizontal, by applying thumbnails-orientation:

<div class="Sirv" data-options="thumbnails:left thumbnails-orientation:horizontal"><img data-src="" /></div>
Zoomable image 1
Zoomable image 2
Zoomable image 3

To position the thumbnails elsewhere on your page, place them in a div wherever you like and give the div a unique ID. Identify that ID in the code for the with a leading # like so:

<div class="Sirv" data-options="thumbnails=#place-div-id-here""><img data-src="" /></div>

The height of horizontal thumbnails or width of vertical thumbnails can be changed via CSS, for example:

  .sirv-zoom-thumbnails.thumbs-horizontal {
    height: 90px;
  .sirv-zoom-thumbnails.thumbs-vertical {
    width: 90px;

Spacing, margin, padding and borders can be adjusted with CSS. For example, a thumbnail border can be added like so:

  .sirv-zoom-thumbnails li {
    border: 1px solid black;

The active thumbnail can be highlighted with CSS like so:

  .sirv-zoom-thumbnails li.sirv-thumb-selected {
    border: 1px dashed red;


Change the background color of the enlarged full-screen image by updating the .sirv-zoom-figure.fullscreen-mode class.

This CSS will make the full-screen background and thumbnail background black:

  .sirv-zoom-figure.fullscreen-mode .sirv-zoom-thumbnails {
    background: #000;


You can apply any of your Sirv profiles (a set of predefined settings) by using the data-profiles attribute in a zoom. In the example below, my-profile is the name of the profile being applied:

<div class="Sirv" data-effect="zoom" data-profiles="my-profile" data-src="">

You can specify particular profiles for different screen-size devices. This is helpful for designing websites with different layouts for mobiles, tablets and large desktop screens. To do this, add each profile, comma separated, with a w suffix and the pixel width of the maximum screen width that each profile is intended for. The profile without a descriptor is the default profile. The example code below has 4 profiles, with the last being the default profile:

<div class="Sirv" data-effect="zoom" data-profiles="car-zoom-small 767w, car-zoom-medium 959w, car-zoom-large 1279w, car-zoom-xlarge">


Change the size of the buttons by using the .sirv-zoom-button CSS class to specify new sizes for width and height:

.sirv-zoom-button {
  width: 20px;
  height: 20px;
.sirv-zoom-nav-controls {
  width: 22px;

Context Menu

The context menu is shown on right-click (Ctrl click on Mac). It looks like this:

Screenshot of right click in Sirv Zoom

The menu provides these options:

  • Zoom in
  • Zoom out
  • Enter Full Screen / Exit Full Screen
  • Download image

The language and text of the 5 items in the context menu can be changed. Set the parameters of textZoomIn, textZoomOut, textEnterFullscreen, textExitFullscreen, textDownload to anything of your choice.

<div class="Sirv" data-options="textZoomIn:New text; textZoomOut:New text; textEnterFullscreen:New text; textExitFullscreen:New text; textDownload:New text;" data-src="">

The menu can be disabled, removing all options, including right-click to download. To disable the context menu, set contextmenu to false like so:

<div class="Sirv" data-options="contextmenu: false;" data-src="">
Disabled right-click menu

The design can be styled using CSS. There are 5 styles available for editing:

  // Style the menu box
    .sirv-contextmenu {
  // Style the menu items
    .sirv-contextmenu li {
  // Style the highlighted menu item
    .sirv-contextmenu li:hover {
  // Style the disabled menu item
    .sirv-contextmenu li[disabled] {
  // Style the line seperator
    .sirv-contextmenu {

Zoom levels

The number of clicks needed to zoom to the final level is determined by the difference in size between the small and large image. Sirv automatically calculates a comfortable level of zoom: deep enough for much greater detail, shallow enough to prevent disorientation.

To add more zoom levels, either upload a larger image to your Sirv account or embed the image at a smaller size in your page.

3000px width image, embedded at 300px (click to zoom 3 times):

Image zoom embedded at 300px width

3000px width image, embedded at 600px (click to zoom twice):

Image zoom embedded at 600px width

Image quality

Your images will be served as WebP images if the browser supports WebP, otherwise JPEG or PNG images will be served. Image quality is 85% by default and can be adjusted.

To serve smaller, faster images, reduce the image quality by adding a quality value to the URI. This code sets a JPEG quality of 70%:

<div class="Sirv" data-effect="zoom">
  <img data-src=""/>

Here’s how 70% quality looks – you may notice more artefacts in the JPEG image, around areas of high contrast:

Image zoom demo

Start/stop zoom

Sirv Zoom will automatically initialize when the DOM is ready.

Alternatively, you can control this yourself with these commands:

  • Sirv.start() – starts all instances of .Sirv on the page.
  • Sirv.stop() – stops all instances of .Sirv on the page.

If you have multiple zooms on the page and need to control a particular one, specify the #id of that zoom:

  • Sirv.start(<#id>) – starts the .Sirv instance with a specific #id.
  • Sirv.stop(<#id>) – stops the .Sirv instance with a specific #id.

To turn off autostart on page load:

  var SirvOptions = {
    autostart: false

Browser compatibility

Sirv Zoom supports all modern browsers – Chrome, Safari, Firefox, Opera and Microsoft Edge. It is also backwards compatibile with many old browsers, including right back to Internet Explorer 8.

This strong browser support ensures your images will zoom on virtually every browser in use today.

Chrome 6 and upYes
Safari 6 and upYes
Firefox 5 and upYes
Opera 15 and upYes
Microsoft EdgeYes
Internet Explorer 8 and upYes

Expert support

For help from a Sirv expert, contact the support team from your Sirv account.

If you don’t have a Sirv account yet, join now.

Was this article helpful?