Sirv image transformation JavaScript SDK

Installation

npm install @sirv/js-sdk

const { SirvClient } = require('@sirv/js-sdk');

Quick Start

const { SirvClient } = require('@sirv/js-sdk');

const sirv = new SirvClient({ domain: 'demo.sirv.com', defaults: { q: 80 } });

// Build a URL
sirv.url('/image.jpg', { w: 300, h: 200, format: 'webp' });
// => https://demo.sirv.com/image.jpg?q=80&w=300&h=200&format=webp

// Generate an image tag
sirv.image('/photo.jpg', { alt: 'A photo' });
// => <img class="Sirv" data-src="https://demo.sirv.com/photo.jpg" alt="A photo">

// Generate a script tag
sirv.scriptTag({ modules: ['spin', 'zoom'] });
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.spin.zoom.js" async></script>

Constructor

new SirvClient(options)

const sirv = new SirvClient({
  domain: 'demo.sirv.com',
  defaults: { q: 80 }
});

url(path, params?)

Build a full Sirv URL. Nested objects are flattened to dot-notation query parameters. Default parameters are merged with the provided params.

// Simple params
sirv.url('/image.jpg', { w: 300, h: 200, format: 'webp' });
// => https://demo.sirv.com/image.jpg?q=80&w=300&h=200&format=webp

// Nested params flatten to dot-notation
sirv.url('/image.jpg', { crop: { type: 'face', pad: { width: 10, height: 10 } } });
// => ...?q=80&crop.type=face&crop.pad.width=10&crop.pad.height=10

// Params override defaults
sirv.url('/image.jpg', { q: 90 });
// => https://demo.sirv.com/image.jpg?q=90

srcSet(path, params?, options?)

Generate a srcset string for responsive images. Supports three modes:

Explicit widths

sirv.srcSet('/image.jpg', { format: 'webp' }, { widths: [320, 640, 960, 1280, 1920] });
// => https://demo.sirv.com/image.jpg?q=80&format=webp&w=320 320w,
//    https://demo.sirv.com/image.jpg?q=80&format=webp&w=640 640w, ...

Auto-generated widths (tolerance)

Generates widths between minWidth and maxWidth, stepping by current *= 1 + tolerance * 2.

sirv.srcSet('/image.jpg', { format: 'webp' }, {
  minWidth: 200, maxWidth: 2000, tolerance: 0.15
});

Device pixel ratios (DPR)

Generates DPR variants with automatic variable quality: q = round(baseQ × 0.75(dpr-1)). Width and height are multiplied by the DPR.

sirv.srcSet('/hero.jpg', { w: 600, h: 400 }, { devicePixelRatios: [1, 2, 3] });
// 1x: q=80, w=600, h=400
// 2x: q=60, w=1200, h=800
// 3x: q=45, w=1800, h=1200

image(path, options?)

Generate an <img> tag for a Sirv image with class="Sirv" and data-src.

sirv.image('/tomatoes.jpg', { alt: 'Fresh tomatoes' });
// => <img class="Sirv" data-src="https://demo.sirv.com/tomatoes.jpg" alt="Fresh tomatoes">

sirv.image('/photo.jpg', {
  transform: { w: 800, format: 'webp' },
  viewer: { autostart: 'visible', threshold: 200 },
  className: 'hero-image'
});
// => <img class="Sirv hero-image" data-src="...?q=80&w=800&format=webp"
//        data-options="autostart:visible;threshold:200">

zoom(path, options?)

Generate a <div> tag for a Sirv zoom viewer with data-type="zoom".

sirv.zoom('/product.jpg');
// => <div class="Sirv" data-src="https://demo.sirv.com/product.jpg" data-type="zoom"></div>

sirv.zoom('/product.jpg', { viewer: { mode: 'deep', wheel: false } });
// => <div ... data-type="zoom" data-options="mode:deep;wheel:false"></div>

spin(path, options?)

Generate a <div> tag for a Sirv 360 spin viewer. No data-type attribute is added (Sirv JS auto-detects .spin files).

sirv.spin('/product.spin');
// => <div class="Sirv" data-src="https://demo.sirv.com/product.spin"></div>

sirv.spin('/product.spin', { viewer: { autostart: 'visible', autospin: 'lazy' } });

video(path, options?)

Generate a <div> tag for a Sirv video.

sirv.video('/clip.mp4');
// => <div class="Sirv" data-src="https://demo.sirv.com/clip.mp4"></div>

model(path, options?)

Generate a <div> tag for a Sirv 3D model viewer.

sirv.model('/shoe.glb');
// => <div class="Sirv" data-src="https://demo.sirv.com/shoe.glb"></div>

gallery(items, options?)

Generate a gallery container with multiple asset divs. Each item can have its own type, transform params, and viewer options. Gallery-level viewer options apply to the container.

Item properties

Gallery options

sirv.gallery([
  { src: '/product.spin' },
  { src: '/front.jpg', type: 'zoom' },
  { src: '/side.jpg', type: 'zoom' },
  { src: '/video.mp4' }
], {
  viewer: { arrows: true, thumbnails: 'bottom' }
});
// => <div class="Sirv" data-options="arrows:true;thumbnails:bottom">
//      <div data-src="https://demo.sirv.com/product.spin"></div>
//      <div data-src="https://demo.sirv.com/front.jpg" data-type="zoom"></div>
//      <div data-src="https://demo.sirv.com/side.jpg" data-type="zoom"></div>
//      <div data-src="https://demo.sirv.com/video.mp4"></div>
//    </div>

scriptTag(options?)

Generate a <script> tag to load Sirv JS. Optionally specify modules to load only what you need.

sirv.scriptTag();
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.js" async></script>

sirv.scriptTag({ modules: ['spin', 'zoom'] });
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.spin.zoom.js" async></script>

Full Examples

Responsive Product Page

const { SirvClient } = require('@sirv/js-sdk');
const sirv = new SirvClient({ domain: 'mystore.sirv.com', defaults: { q: 80 } });

// Responsive image with srcset
const srcset = sirv.srcSet('/hero.jpg', { format: 'webp' }, {
  widths: [320, 640, 960, 1280, 1920]
});
console.log(`<img srcset="${srcset}" sizes="100vw">`);

// Product gallery with zoom, spin, and video
const gallery = sirv.gallery([
  { src: '/products/shoe.spin' },
  { src: '/products/shoe-front.jpg', type: 'zoom' },
  { src: '/products/shoe-side.jpg', type: 'zoom' },
  { src: '/products/shoe-video.mp4' }
], { viewer: { thumbnails: 'bottom' } });

// Load Sirv JS for spin + zoom
const script = sirv.scriptTag({ modules: ['spin', 'zoom'] });

Thumbnail Grid with Face Crop

const images = ['/team/alice.jpg', '/team/bob.jpg', '/team/carol.jpg'];
const html = images.map(path =>
  sirv.image(path, {
    transform: { w: 200, h: 200, crop: { type: 'face' } },
    alt: path.split('/').pop()
  })
).join('\n');