Sirv .NET SDK Documentation

Installation

dotnet add package Sirv.Client

using Sirv;

Quick Start

using Sirv;

var sirv = new SirvClient("demo.sirv.com", new Dictionary<string, object> { { "q", 80 } });

// Build a URL
sirv.Url("/image.jpg", new Dictionary<string, object> { { "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", new ImageOptions { Alt = "A photo" });
// => <img class="Sirv" data-src="https://demo.sirv.com/photo.jpg" alt="A photo">

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

Constructor

new SirvClient(domain, defaults?)

Parameter	Type	Description
`domain`	string	Required. Sirv domain (e.g. `"demo.sirv.com"`)
`defaults`	Dictionary<string, object>?	Default query parameters merged into every URL

var sirv = new SirvClient("demo.sirv.com");

var sirv = new SirvClient("demo.sirv.com", new Dictionary<string, object> { { "q", 80 } });

Url(path, parameters?)

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

Param	Type	Description
`path`	string	Asset path (e.g. `"/image.jpg"`)
`parameters`	Dictionary<string, object>?	Transformation parameters (nested dictionaries are flattened)

// Simple params
sirv.Url("/image.jpg", new Dictionary<string, object> { { "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", new Dictionary<string, object>
{
    { "crop", new Dictionary<string, object>
        {
            { "type", "face" },
            { "pad", new Dictionary<string, object> { { "width", 10 }, { "height", 10 } } }
        }
    }
});
// => ...?q=80&crop.type=face&crop.pad.width=10&crop.pad.height=10

// Params override defaults
sirv.Url("/image.jpg", new Dictionary<string, object> { { "q", 90 } });
// => https://demo.sirv.com/image.jpg?q=90

SrcSet(path, parameters?, options?)

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

Explicit widths

sirv.SrcSet("/image.jpg", new Dictionary<string, object> { { "format", "webp" } },
    new SrcSetOptions { Widths = new[] { 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", new Dictionary<string, object> { { "format", "webp" } },
    new SrcSetOptions { 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", new Dictionary<string, object> { { "w", 600 }, { "h", 400 } },
    new SrcSetOptions { DevicePixelRatios = new[] { 1.0, 2.0, 3.0 } });
// 1x: q=80, w=600, h=400
// 2x: q=60, w=1200, h=800
// 3x: q=45, w=1800, h=1200

SrcSetOptions

Property	Type	Description
`Widths`	int[]?	Explicit list of widths
`MinWidth`	int?	Minimum width for auto-generation
`MaxWidth`	int?	Maximum width for auto-generation
`Tolerance`	double?	Step tolerance (default 0.15)
`DevicePixelRatios`	double[]?	DPR values (e.g. `new[] { 1.0, 2.0, 3.0 }`)

Image(path, options?)

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

ImageOptions

Property	Type	Description
`Transform`	Dictionary<string, object>?	Transformation parameters for the URL
`Viewer`	Dictionary<string, object>?	Viewer options (serialized to `data-options`)
`Alt`	string?	Alt text
`ClassName`	string?	Additional CSS class(es)

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

sirv.Image("/photo.jpg", new ImageOptions
{
    Transform = new Dictionary<string, object> { { "w", 800 }, { "format", "webp" } },
    Viewer = new Dictionary<string, object> { { "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".

ViewerDivOptions

Property	Type	Description
`Transform`	Dictionary<string, object>?	Transformation parameters
`Viewer`	Dictionary<string, object>?	Viewer options
`ClassName`	string?	Additional CSS class(es)

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

sirv.Zoom("/product.jpg", new ViewerDivOptions
{
    Viewer = new Dictionary<string, object> { { "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).

ViewerDivOptions

Property	Type	Description
`Viewer`	Dictionary<string, object>?	Viewer options
`ClassName`	string?	Additional CSS class(es)

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

sirv.Spin("/product.spin", new ViewerDivOptions
{
    Viewer = new Dictionary<string, object> { { "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.

GalleryItem

Property	Type	Description
`Src`	string	Required. Asset path
`Type`	string?	Asset type override (e.g. `"zoom"`)
`Transform`	Dictionary<string, object>?	Per-item transformation params
`Viewer`	Dictionary<string, object>?	Per-item viewer options

GalleryOptions

Property	Type	Description
`Viewer`	Dictionary<string, object>?	Gallery-level viewer options
`ClassName`	string?	Additional CSS class(es)

sirv.Gallery(new[]
{
    new GalleryItem { Src = "/product.spin" },
    new GalleryItem { Src = "/front.jpg", Type = "zoom" },
    new GalleryItem { Src = "/side.jpg", Type = "zoom" },
    new GalleryItem { Src = "/video.mp4" }
}, new GalleryOptions
{
    Viewer = new Dictionary<string, object> { { "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.

ScriptTagOptions

Property	Type	Description
`Modules`	string[]?	Modules to load (e.g. `new[] { "spin", "zoom" }`)
`Async`	bool	Add async attribute (default `true`)

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

sirv.ScriptTag(new ScriptTagOptions { Modules = new[] { "spin", "zoom" } });
// => <script src="https://scripts.sirv.com/sirvjs/v3/sirv.spin.zoom.js" async></script>

Full Examples

Responsive Product Page

using Sirv;

var sirv = new SirvClient("mystore.sirv.com", new Dictionary<string, object> { { "q", 80 } });

// Responsive image with srcset
var srcset = sirv.SrcSet("/hero.jpg",
    new Dictionary<string, object> { { "format", "webp" } },
    new SrcSetOptions { Widths = new[] { 320, 640, 960, 1280, 1920 } });
Console.WriteLine($"<img srcset=\"{srcset}\" sizes=\"100vw\">");

// Product gallery with zoom, spin, and video
var gallery = sirv.Gallery(new[]
{
    new GalleryItem { Src = "/products/shoe.spin" },
    new GalleryItem { Src = "/products/shoe-front.jpg", Type = "zoom" },
    new GalleryItem { Src = "/products/shoe-side.jpg", Type = "zoom" },
    new GalleryItem { Src = "/products/shoe-video.mp4" }
}, new GalleryOptions
{
    Viewer = new Dictionary<string, object> { { "thumbnails", "bottom" } }
});

// Load Sirv JS for spin + zoom
var script = sirv.ScriptTag(new ScriptTagOptions { Modules = new[] { "spin", "zoom" } });

Thumbnail Grid with Face Crop

var images = new[] { "/team/alice.jpg", "/team/bob.jpg", "/team/carol.jpg" };
var html = string.Join("\n", images.Select(path =>
    sirv.Image(path, new ImageOptions
    {
        Transform = new Dictionary<string, object>
        {
            { "w", 200 }, { "h", 200 },
            { "crop", new Dictionary<string, object> { { "type", "face" } } }
        },
        Alt = Path.GetFileNameWithoutExtension(path)
    })
));