Sirv Spin documentation

This documentation explains how to embed 360 spins in your websites/apps.

Sirv rapidly generates 360° and 3D spins. You can embed in websites, apps and social media. Some samples are shared in your account. New users can create an account.

Create a spin

Sirv automatically detects spins by searching for images that appear to be in a sequence. It recognizes many different sequences, such as:

  • adidas-zx-flux-01.jpg
  • adidas-zx-flux-02.jpg
  • adidas-zx-flux-03.jpg
  • etc.

3D spins (also known as multi-row or multi-axis spins) have multiple rows and columns, allowing images to be rotated up/down/left/right. Sirv recognizes these spins by scanning for two separate sets of digits in the file name. The first set of digits should refer to the row, the second to the column.

The file names below would generate a spin of 4 rows and 8 columns (32 images in total):


Spins are typically photographed using between 24 and 36 images but any number of images from 2 to 1000 can be used. Keep in mind that the more images, the longer the spin will take to load.

Sirv automatically creates a .spin file and provides you with code to embed the 360 spin into your page. The .spin file contains the location of all the images in the spin, plus any custom settings you have chosen. Each .spin file is only 1-2kb in file size. They count towards your Sirv storage allowance and do not duplicate your images.

You can safely delete .spin files that you don’t require. If you delete a .spin file by mistake, you can retrieve it from Trash or trigger the creation of a new file by reuploading an image or changing the name of one of the images and then changing it back again.

Spins will be automatically generated when:

  • The image names contain a sequence of ascending numerals.
  • Between 8 and 1000 images make up the sequence.
  • Numerals do not exceed the value 1024.

Spins can also be created manually, from 2 or more images, regardless of their file name.

To manually create a spin:

  1. Upload the images to your Sirv account.
  2. Select all the images to show in your spin.
  3. Click the “Create spin” button.

Embed a 360 spin

Click on any spin in your Sirv account to a preview of the spin. Underneath is the code to embed the spin in your page.

The JavaScript code should be pasted before the of your HTML page (or anywhere else on your page):

<script src=""></script>

The spin code should be pasted where you want the spin to appear:

Go ahead and paste that code above into your page and you’ll see the spinning power drill.


Alternatively, spins can be embedded with an iframe, instead of the standard Sirv div and script code described above.

Advantages of iframe:

  • Can often be embedded in your page when other embed methods cannot.

Disadvantages of iframe:

  • Full-screen does not work on all browsers.
  • Scrollbars might be unnecessarily added to your page.

The disadvantages mean that iframes are not recommended unless there is no other option. For example, some CMS or website control panels restrict you from adding any < script > code to your page, so iframe is the solution. Facebook also restricts < script > tags in Facebook pages, so iframe is necessary. (While Facebook pages require iframe, Facebook posts have an diferent method – see below).

To embed an iframe, copy the code from the iframe option of your spin:

Embed 360 spin with iframe

Copy the code below to paste this demo into your page:

<iframe src="" width="300" height="300" frameborder="0" allowfullscreen="allowfullscreen"></iframe>

Spin options

spindragdrag / hoverMethod for spinning the image.
autospinonceonce / twice / infinite / offAutomatically spin the image.
autospinSpeed3600numericThe time (ms) taken to complete 1 rotation.
autospinStartloadload / hover / click / or combination e.g. load,hoverStart autospin on page load, click or hover.
autospinStopclickclick / hover / neverStop autospin on click, hover or never.
autospinDirectionclockwiseclockwise / anticlockwise / alternate-clockwise / alternate-anticlockwiseDirection of spin.
fullscreentruetrue / falseEnable full-screen spin if large images exist.
zoom2.50-10Zoom level on click (0 = disabled)
magnifytruetrue / falseEnable magnifier if large images exist.
magnifierShapeinnerinner / circle / squareShape of magnifying glass.
magnifierWidth80%% of small image width or fixed size in pxWidth of magnifying glass (if circle or square).
initializeOnloadload / hover / clickWhen to download the images.
speed500-100Speed of spin while dragging (100 = fast).
startColumnautonumeric or autoStart spin with image in src or specify another column.
startRowautonumeric or autoStart spin with image in src or specify another row.
reverseRotationfalsetrue / falseReverse rotation on X-axis.
reverseColumnfalsetrue / falseReverse rotation on X-axis.
reverseRowfalsetrue / falseReverse rotation on Y-axis.
swapRowsColumnsfalsetrue / falseDisplay a vertical spin.
columnIncrement1numericLoad only every second (2) or third (3) column so that spins load faster.
rowIncrement1numericLoad only every second (2) or third (3) row so that spins load faster.
loopColumntruetrue / falseContinue spin after the last image on X-axis.
loopRowfalsetrue / falseContinue spin after the last image on Y-axis.
rightClickfalsetrue / falseShow right-click menu on the image.
smoothingtruetrue / falseSmoothly stop the image spinning.
mousewheelStep3numericNumber of frames to spin on mousewheel.
loadingTextLoading…textText shown while loading.
fullscreenLoadingTextLoading large spin…textText shown while full-screen images loading.
hinttruetrue / falseHide the message & arrows for spinning the image.
hintTextDrag to spintextText shown once images have loaded.
mobileHintTextSwipe to spintextText shown on mobile devices once images have loaded.
emulate3Dfalsetrue/falseRotate a single row spin by dragging up/down as well as left/right.

How to apply spin options

Choose how you want to apply your options:

  • Profile – save a whole set of options in a profile and apply that to as many spins as you wish.
  • Spin file – edit the options of a spin file. Only that .spin will be edited.
  • URL – attach options to the end of the spin URL. Quick and easy.
  • JavaScript – add a script in your page. This can be useful for gaining advanced programmatic control over the spin.

Spin images

Your spins will be created with 3 sizes of image:

  • Main images – shown within your page
  • Zoom images – shown on click
  • Full-screen images – shown when entering full-screen mode

The dimensions of the images are determined like so:

  • Main images – automatically fits the width or height of the containing element of your page (div/table/spans etc.).
  • Zoom images – automatically created at 2.5 times larger than the main images.
  • Full-screen images – automatically fits the users screen dimensions e.g. a 1366 x 768px display will be served an image to fit inside, either 1366px width or 768px height.

You can change the zoom dimensions by changing the zoom option. Click the example below to zoom in at 4 times magnification:

If you wish to specify your desired zoom magnification in pixels, this can be done like so:

  1. Set the “zoom” option to “1” in the spin options.
  2. Set your desired zoom size under Spin options -> Images -> Zoom image -> Scale.

Zoom is automatically enabled if your original images are at least 20% bigger than the main image. If the original images you uploaded are smaller than this, no zoom or full-screen options will be available.

You can make Sirv scale your images beyond their original dimensions by changing the scale.option to fit, fill or ignore. The maximum size you can scale up to is 10,000px. Scaling images up results in loss of clarity, so the ideal solution is to upload higher resolution images.

Image size

You are recommended to upload your highest resolution images to Sirv (4000px width or larger if you have them). This will allow you to display the sharpest possible images. Modern displays are gaining higher and higher definition, so by uploading your largest images, you are protecting yourself for the future. Consider that some displays already go beyond 5000px:

MacBook Pro (3rd generation) 13″2560×1600 pixels
MacBook Pro (3rd generation) 15″2880×1800 pixels
iMac (Intel-based) Slim Unibody iMac 27″5120×2880 pixels

Not only do high resolution images give beautiful clarity zooms, they will give you greater creative options such as cropping into images in artistic ways.

We recommend at minimum to upload images of 2500px width to enjoy a high quality zoom.

Full-screen button

Sirv displays a button in the top right corner of the 360 spin. The default buttons are:

Full-screen buttons

You can remove the button by setting the Fullscreen option to disabled in either the spin settings or a profile:

You can change the buttons to a different design by adding the following CSS to your page:

  .sirv-spin-button.fullscreen {
    background-image: url(spin/graphics/buttons06.png);
  .sirv-spin-button.fullscreen-exit {
    background-image: url(spin/graphics/buttons06.png);



To use your own custom-designed buttons, save your buttons with any name and upload them to any directory of your Sirv account. They should use the same dimensions as the default buttons. For example:

Full-screen buttons

Full-screen background

The enlarged full-screen spin has a white background by default.

The background color can be changed via the CSS style sirv-spin-fullscreen. To change it to black, add the following CSS code to your HTML page:

  .sirv-spin-fullscreen {
    background: #000;



Loading bar

A loading bar shows the image download progress.

The position, animation and design of the loading bar can be customized by changing these styles:

.sirv-spin-loading {}
.sirv-spin-progress-bar {}
.sirv-spin-progress-bar-state {}
.sirv-spin-progress-text {}
.sirv-spin-fullscreen .sirv-spin-loading-box {}
.sirv-spin-fullscreen .sirv-spin-progress-bar {}
.sirv-spin-fullscreen .sirv-spin-progress-bar-state {}
.sirv-spin-fullscreen .sirv-spin-progress-text {}


Spins can be rotated with the mousewheel. By default, each click of the mousewheel rotates the spin by 3 frames. This can be changed to any other amount.

To disable mousewheel spin, set mousewheelStep to 0. Here’s a spin with mousewheel disabled:

Show/hide a spin

Your 360 spin will start downloading automatically when the DOM is ready. Once all images have downloaded, it will auto-rotate by default.

Your spin will not download if it is hidden on your page. This is a common scenario when displaying product images in a carousel where the spin is not the primary image (example).

Hidden spins will download on demand. Typically, they would be shown upon click of a thumbnail, button or text link.

Spins can be hidden in many ways, for example with display:none inside a div or another HTML element. You can use JavaScript to show the div when needed.

To avoid the delay of images loading when a hidden spin is requested, you can download hidden spins on page load. One way is to show the spin code as normal (not hidden) and hide it in a visual way, for example with opacity:0.

Another method to control trigger when images are downloaded is to use the Sirv Spin API.

Sirv Spin API

Start/stop spin

Your 360 spin will automatically start downloading when the DOM is ready. Once all images have downloaded, it will auto-rotate by default.

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

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

  • 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, apply this:

  var SirvOptions = {
    autostart: false

API methods for spin behaviour

Control the behaviour of a spin, for example with buttons on your spin/page, using these API calls:

  • Sirv.instance(‘#id’).play([frames]) – Rotate by +/-X number of frames on X-axis. If frames are omitted, start infinite spin.
  • Sirv.instance(‘#id’).pause() – Stop rotation.
  • Sirv.instance(‘#id’).rotate(columns, [rows]) – Rotate by +/-X number of frames on X-axis and/or Y-axis.
  • Sirv.instance(‘#id’).rotateX(frames) – Rotate by +/-X number of frames on X-axis.
  • Sirv.instance(‘#id’).rotateY(frames) – Rotate by +/-X number of frames on Y-axis.
  • Sirv.instance(‘#id’).jump(rows) – Jump by +/-X number rows.
  • Sirv.instance(‘#id’).zoomIn() – Zoom in to current frame.
  • Sirv.instance(‘#id’).zoomOut() – Zoom out of current frame.
  • Sirv.instance(‘#id’).fullscreen() – Enter full-screen.
  • Sirv.instance(‘#id’).currentFrame() – Get the current row and column number (currentFrame.row / currentFrame.column).

Where #id is the id of the spin in your div.

Apply it by passing #id, like this:

Or apply it by passing the reference to the div, like this:

Animated GIFs

Sirv can host animated GIFs of your spins, with on-demand options to resize, crop and apply lossy optimization.

Sirv can also generate new animated GIFs from a set of images. Simply create a spin, which can be instantly displayed as a GIF. It is a great way to show spins in places where JavaScript is not permitted, such as:

  • Emails
  • Forums
  • Facebook posts
  • Twitter posts
  • Google+ posts
  • LinkedIn articles
  • Classified ad sites (Gumtree, Craigslist etc.)

Sirv automatically generates GIFs of up to:

  • 72 frames
  • 640px/500px width/height

If your spin has more than 72 frames, Sirv will drop some frames, automatically calculating the optimal space between frames for a smoothly animated GIF. If you specify dimensions greater than 640px width or 500px height, Sirv will scale down the GIF to fit within those dimensions.

Create a GIF

To display any of your spins as a GIF, add the ?image parameter to the URL, along with w (width) and/or h (height). For example, here is a GIF with 300px height:

360 degree spin - animated GIF

Reduce number of frames

You can reduce the number of frames in a GIF by explicitly setting the number. After the ?image parameter, enter the number of frames the GIF should have. For example, this spin has only 18 frames:

Animated GIF with 18 frames

Reduce GIF file size

Sirv generates very high quality GIFs by default. This gives excellent clarity, however, a GIF with large dimensions and a great number of frames will have a very large file size. It may be slow to download for your visitors.

To overcome this, consider applying lossy compression. It can reduce the file size by 40-60%, with a small reduction in image quality.

To apply lossy compression, add the gif.lossy parameter to the URL. It’s value can be from 0 to 100, where 0 is no compression and 100 is maximum compression (lowest quality and smallest file size). This example has 80% compression:

Animated GIF with 80% lossy compression

Compare that GIF against the previous example and you’ll notice a visible reduction in image quality. The quality differs depending on the images – there is no single ideal compression value for all GIFs – so try a few variations to see what amount of compression suits your images.

Image dimensions also have a big impact on file size. Compare the difference in file size of the spinning drill at different dimensions:

WidthFramesFile size without compressionFile size with 80% compressionReduction

Change the GIF design

You can use the entire collection of Sirv dynamic imaging options (speed, watermark, text, frame, scale, crop etc.) to customize your animated GIF. The example below shows a larger image with a text overlay:

360 degree spin - animated GIF

The image URL looks like this:

You can also add popular dynamic image options to uploaded GIFs including cropping, resizing and lossy compression. Here’s how it can look:

Change the GIF scale

You can resize both your pre-created GIFs and spin GIFs by specifying width/height in the URL. Add w or h at the end of the URL, and Sirv will immediately resize the GIF according to the specified dimensions.

This GIF was 400px width and has been scaled to 300px width:

This GIF has been resized from 400px to 150px height:

Upscaling the GIF means you can lose in clarity. Upload the largest possible images to Sirv for the highest quality.

scale.option controls how GIFs are scaled. Set it to fill if you want to fill a certain area. In the example below, Sirv applies 450px width and ignores 150px height:

Crop GIF

Crop your GIFs by applying ch (crop height) or/and cw (crop width) to the URL. This GIF has been cropped to 300px from 500px:

Cropping by default starts from the upper left corner. Change this by applying cx (width) and cy (height) to the URL:

Set cx and cy to center to crop from the middle like this:

You can resize and crop your GIFs at the same time. For example, the GIF was scaled to 600px, and then cropped to central 380 pixels width by 120 pixels height with 60px indentation:

Square GIF thumbnails

Sirv has a thumbnail parameter for quickly creating square thumbnail images. Regardless of aspect ratio, your images will be cropped square from their central point. The thumbnail parameter can be used to create static images or animated GIFs.

The example below creates a 150px square thumbnail of the animated GIF:

Image thumbnail, generated on demand

256px is the largest thumbnail size available.

Add GIFs to a web page

Embed a GIF just like any image, using an img tag, for example:

<img src=";scale.height=200" />

Add GIFs to an email

GIFs can be embedded in the content of an HTML with an img tag, like above. However, most email programs and email marketing tools allow you to embed an image simply with the URL. In Gmail for example, the Gmail embed image icon icon lets you add an image from a URL. Try it by copying and pasting this URL:

Add GIFs to Facebook / Google+

The best way to embed a spin in a Facebook or Google+ post is to reference the spin file itself. You don’t need to reference a GIF, Sirv automatically serves animated GIFs to Facebook. Try this yourself – go ahead and paste this URL into a Facebook post. When you submit it, you’ll see the animated GIF:

If a user clicks the GIF, they will be taken to the fully-interactive version of your spin with drag, zoom and full-screen features.

Auto spin

Spins can rotate automatically. By default, one full rotation is shown after all the images have downloaded. You can change this to spin twice, infinitely or turn off auto-spin.

This example shows infinite spin:


The initialization of the spin determines when the images are downloaded. By default, images are downloaded automatically at the end of the page load. To reduce data transfer, you can set the spin images to download on click or hover. Until then, the first image of the spin is shown.

Go to your spin or profile settings and set initializeOn to either hover or click:

The demo below initializes on click:

The demo below initializes on hover:

First image in spin

Sirv has a thumb parameter to automatically serve the first image in a spin. This image will always match the image the user sees when a spin loads.

The thumbnail can be any size and can have any of the Sirv dynamic imaging settings applied to it.

To fetch the first image of a spin, enter ?thumb after the .spin reference. For example:

Resize the image with the usual Sirv dynamic imaging options, for example:

Image at 200px width

Apply any other Sirv dynamic imaging settings as you wish, for example:

Image with text overlay

By default, the first image is column 1. In the case of a 3D spin, the first image is column 1, row 1. To choose another image, right-click the spin, choose Edit and choose the start row and start column:

When you choose an image, the settings are saved in the .spin file.

You can also update the .spin file directly itself – it is a JSON text file. This can be used to automate your workflow for example with a local application you use for managing your spins.

Text overlays

You can overlay text or image layers to your spins to display things like product names, copyright information or logo watermarks.

Apply text overlays either by creating a profile or editing the .spin file. A profile is usually best because it permits you to apply the same settings to multiple spins.

Example of a spin with a text profile:


You can display text in different languages by creating a profile for each language you wish to provide. Each profile can contain different UI messages (e.g. Swipe to spin) or button alt text (e.g. Full-screen). Once you’ve created your profiles, one for each language, serve the profile for the language the customer requires. For example, if you named your profile “spin-spanish”, append it to the URL like so:

Retina images

Sirv automatically creates and serves hi-res images to retina devices. These images have 4 times the number of pixels as normal resolution images, so they look very sharp on iPhone, iPad and other retina screens.

Retina images have larger file sizes than standard images. To compensate for this, Sirv automatically applies stronger image compression to reduce their large size. This reduction in JPEG/WebP quality to 60% has a very subtle and usually indistinguishable effect on image quality, so users will see stunningly sharp images which load quickly.

JSON .spin files

The .spin text files automatically generated by Sirv use JSON code to reference the images in your spin and any additional settings for the spin.

When you edit files in your Sirv control panel, the JSON code is updated. You don’t need to write or edit any JSON code under normal Sirv usage.

You’re able to create and edit .spin files manually. This can be useful for programmatically automating the creation and management of many spins. You can open .spin and .profile files in a text editor to see how they are structured. You can create brand new .spin files by following the format Sirv uses to construct a spin file.

Example spin file:

  "pattern": "^animated\ wallet\-(\d+)\.jpg$",
  "layers": {
    "1": {
      "1": "Animated Wallet-1.jpg",
      "2": "Animated Wallet-2.jpg",
      "3": "Animated Wallet-3.jpg",
      "4": "Animated Wallet-4.jpg",
      "5": "Animated Wallet-5.jpg",
      "6": "Animated Wallet-6.jpg",
      "7": "Animated Wallet-7.jpg",
      "8": "Animated Wallet-8.jpg",
      "9": "Animated Wallet-9.jpg",
      "10": "Animated Wallet-10.jpg",
      "11": "Animated Wallet-11.jpg",
      "12": "Animated Wallet-12.jpg",
      "13": "Animated Wallet-13.jpg",
      "14": "Animated Wallet-14.jpg",
      "15": "Animated Wallet-15.jpg",
      "16": "Animated Wallet-16.jpg",
      "17": "Animated Wallet-17.jpg",
      "18": "Animated Wallet-18.jpg",
      "19": "Animated Wallet-19.jpg",
      "20": "Animated Wallet-20.jpg",
      "21": "Animated Wallet-21.jpg",
      "22": "Animated Wallet-22.jpg",
      "23": "Animated Wallet-23.jpg",
      "24": "Animated Wallet-24.jpg",
      "25": "Animated Wallet-25.jpg",
      "26": "Animated Wallet-26.jpg",
      "27": "Animated Wallet-27.jpg",
      "28": "Animated Wallet-28.jpg",
      "29": "Animated Wallet-29.jpg",
      "30": "Animated Wallet-30.jpg",
      "31": "Animated Wallet-31.jpg",
      "32": "Animated Wallet-32.jpg"
  "settings": {
    "retina": false

Likewise, you can create and edit .profile files. These JSON files can contain spin settings, allowing you to apply the same profile to many spins and have all the settings stored and updatable in one place.

Example .profile file:

  "spin": {
    "images": {
      "fullscreen": {
        "canvas": {
          "height": "66.666%"
      "zoom": {
        "canvas": {
          "height": "66.666%"
      "main": {
        "canvas": {
          "height": "66.666%"
    "startRow": "2",
    "hintText": "Drag to spin",
    "zoom": 2.5,
    "retina": false

Example profile with a text overlay:

  "image": {
    "text": {
      "text": "Also available in black",
      "style": "simple",
      "position": "south",
      "size": "60%",
      "font": {
        "family": "Lato"
      "color": "black",
      "opacity": 50
  "spin": {
    "autospin": "infinite",
    "autospin-speed": "10"
    "zoom": 2.5

To take a closer look at .spin and .profile files, download them and open them in a text editor. The files can be uploaded and downloaded just like any other file, by FTP, S3 or through your Sirv control panel.

The example below shows the settings section of the .spin file, with infinite spin, faster speed and magnifier and full-screen disabled:

  "settings": {
    "autospin": "infinite",
    "autospinSpeed": 2000,
    "autospinStart": "click",
    "magnify": false,
    "fullscreen": false

These same settings could be applied in a profile like so:

  "spin": {
    "autospin": "infinite",
    "autospinSpeed": 2000,
    "autospinStart": "click",
    "magnify": false,
    "fullscreen": false

The example below has hover to spin, faster speed and a round magnifier:

  "spin": {
    "spin": "hover",
    "speed": 60,
    "magnifierShape": "circle"

Disable spin detection

If you’re not using Sirv for 360 spins, you can turn off the automatic creation of .spin files like so:

  1. Go to your Sirv account.
  2. Right-click the folder containing your images.
  3. Click “Options”.
  4. Set “Scan for spins” to “Never” (screenshot below).

Get expert help

If you need assistance with Sirv spin, please contact our support team from your account.

Was this article helpful?