API

On this page

Use the API for advanced control over the images, spins and videos in Sirv Media Viewer.

Global API

Method Parameters Description
Sirv.start (selector or element) Starts Sirv instance(s) by DOM query selector, or by HTML element
Sirv.stop (selector or element) Stops Sirv instance(s) by DOM query selector, or by HTML element
Sirv.on (event name) Attach an event handler for Sirv event
Sirv.off (event name) Remove an event handler
Sirv.getInstance (selector or element) Get viewer or lazy image instance by DOM query selector, or by HTML element
Sirv.viewer.getInstance (selector or element) Get viewer instance by DOM query selector, or by HTML element
Sirv.lazyImage.getInstance (selector or element) Get lazy image instance by DOM query selector, or by HTML element

Example code:

<script>
// Start all Sirv instances on the page:
Sirv.start();

// Start Sirv instances that match the provided selector:
Sirv.start('.product-view .Sirv');

// Attach event handler
Sirv.on('viewer:beforeSlideIn', (nextItem) => {
    console.log(nextItem);
});
</script>

Viewer API

Method Parameters Description
isReady Check if a viewer instance is ready
isFullscreen Check if a viewer instance is in fullscreen
fullscreen Switch to full screen mode
next Switch to next item
prev Switch to previous item
jump (index or item id) Switch to a particular item by index or by id (data-id)
play (delay) Start viewer autoplay. If the delay argument is passed, it will override the slide.delay setting.
pause Pause viewer autoplay
items (filters) Get viewer items. Filters: { enabled: true } - only enabled items; { enabled: false } - only disabled items.
itemsCount (filters) Get the number of viewer items. Filters: { enabled: true } - only enabled items; { enabled: false } - only disabled items.
child (index or item id) Get reference to a particular item by index or by id (data-id)
enableItem (index or item id) Enable a particular item by index or by id (data-id)
disableItem (index or item id) Disable a particular item by index or by id (data-id)
insertItem (DOM element, index) Add item to the viewer at specified index. If index omitted, add item to the end.
removeItem (index or item id) Remove item from the viewer by index or by id (data-id)
enableGroup (name of group or array from names) Enable a particular group by group name (data-group)
disableGroup (name of group or array from names) Disable a particular group by group name (data-group)
switchGroup (name of group or array from names) Disable enabled groups and enable particular group
sortItems (array from component names or empty) Sort slides by itemsOrder option or array from component names

Example script to replace one gallery with another:

<script>
  // Check if viewer with `id="my-viewer"` is ready:
  Sirv.viewer.getInstance('#my-viewer').isReady();

  // Switch to the next item:
  Sirv.viewer.getInstance('#my-viewer').next();

  // Disable (exclude) 4th item in the viewer:
  Sirv.viewer.getInstance('#my-viewer').disableItem(3);
</script>

Example script to pause a slide on hover:

<script>
  // Pause on entry:
  document.querySelector('#slideshow').addEventListener('mouseenter', () => { Sirv.viewer.getInstance('#slideshow').pause(); });
  
  // Play on exit:
  document.querySelector('#slideshow').addEventListener('mouseleave', () => { Sirv.viewer.getInstance('#slideshow').play(); });
</script>

Example script to show/hide items in a gallery:

<script>
  // Hide items in the "color-navy" group
  Sirv.getInstance('#example-viewer-1').disableGroup('color-navy');
  
  // Show items from the "color-brown" and "size-m" groups
  Sirv.getInstance('#example-viewer-1').enableGroup(['color-brown', 'size-m']);
  
  // Show items from the "color-yellow" group and hide all other items
  Sirv.getInstance('#example-viewer-1').switchGroup('color-yellow');
</script>

Spin API

Method Parameters Description
isInitialized Check if Spin instance is initialized
isReady Check if Spin instance is ready
play (duration, type) Start auto-spin rotation
pause Stop autospin
rotate (columns, [rows]) Rotate by X number of frames on X-axis and/or Y-axis
rotateX (frames) Rotate by X number of frames on X-axis
rotateY (frames) Rotate by X number of frames on Y-axis
jumpRows (row) Jump to a specific row
jumpCols (column) Jump to a specific column
zoomIn Zoom in to current frame
zoomOut Zoom out of current frame
isZoomed Check if the current frame is zoomed
currentFrame Get current frame: {rows: XX, cols: XX}

Example script to rotate the spin:

<script>
// Check if Spin component spin is initialized:
Sirv.getInstance('#my-viewer-id').child(2).spin.isInitialized();

// Check if Spin component is ready:
Sirv.getInstance('.product-view .Sirv').child('spin-item').spin.isReady();

// Start rotate of spin:
Sirv.getInstance('#my-viewer-id').child(2).spin.play(3600, 'row');
</script>

Zoom API

Method Parameters Description
isReady Check if Zoom instance ready
isZoomed Check if image is zoomed in
zoomIn Zoom in to image.
zoomOut Zoom out of image

Example code:

<script>
// Check if component zoom is ready:
Sirv.getInstance('#my-viewer').child(3).zoom.isReady();

// Zoom in to image:
Sirv.getInstance('.product-view .Sirv').child('zoom-item').zoom.zoomIn();
</script>

Video API

Method Parameters Description
isReady Check if video instance is ready

Example code:

<script>
// Check if Video component is ready:
Sirv.viewer.getInstance('#my-viewer').child('video-item').video.isReady();
</script>

Image API

Method Parameters Description
isReady Check if image instance is ready
resize Force image resize

Example code:

<script>
// Check if Image component is ready:
Sirv.viewer.getInstance('#my-viewer').child('image-item').image.isReady();

// Force image resize:
Sirv.viewer.getInstance('#my-viewer').child(4).image.resize();
</script>

Lazy image API

Method Parameters Description
isReady Check if lazy image instance is ready
resize Force image resize

Example code:

<script>
// Check if Lazy Image is ready:
Sirv.lazyimage.getInstance('#my-lazy-image').isReady();

// Force image resize:
Sirv.lazyimage.getInstance('#my-lazy-image').resize();
</script>

Hotspots API

Method Parameters Description
.add(hotspotSettings) hotspotSettings (JSON | Array<JSON>) Add hotspot(s) and settings
.remove(index) index (number) Remove one hotspot
.removeAll() Remove all hotspots
.enable(index) index (number) Enable a particular hotspot
.disable(index) index (number) Disable a particular hotspot
.list() List all hotspots
.setVisibility(index) index (number) Show/hide message popup or tooltip

Example code to hide hotspots in fullscreen:

<script>
const disableHotspots = (hotspotsApi) => {
  hotspotsApi.list().forEach((node, index) => hotspotsApi.disable(index));
};

const enableHotspots = (hotspotsApi) => {
  hotspotsApi.list().forEach((node, index) => hotspotsApi.enable(index));
};

Sirv.on('viewer:fullscreenIn', (e) => {
  e.items().forEach(item => {
    const componentApi = item[item.component];
    if (componentApi.hotspots && componentApi.isReady()) {
      disableHotspots(componentApi.hotspots);
    }
  });
});

Sirv.on('viewer:fullscreenOut', (e) => {
  e.items().forEach(item => {
    const componentApi = item[item.component];
    if (componentApi.hotspots && componentApi.isReady()) {
      enableHotspots(componentApi.hotspots);
    }
  });
});

Sirv.on('spin:ready', (e) => {
  if (e.parent().parent().isFullscreen() && e.hotspots) {
    disableHotspots(e.hotspots);
  }
});
</script>

Was this article helpful?

Get help from a Sirv expert

help ukraine help ukraine Powered by Ukrainian determination and British ingenuity

How can you support Ukraine