Responsive Images API in .net

Creating perfect responsive images can be really hard.

Aspects which are covered

  1. Creating img tags with perfect srcsets
  2. Creating picture tags with perfect source tags for each appropriate format and size
  3. Automatically using [Settings] to create the predefined sizes...
  4. ...or manually specify other sizes

Example

@using ToSic.Sxc.Services;
@{
  var imgService = GetService<IImageService>();
  var blogPic = imgService.Picture(blogPost.Image);
}
@blogPic

TODO: LINK TO EXAMPLES

How This Works

Internally this is what will happen:

  1. The format of the file is checked, to detect if other formats could be converted to (like jpg cound also be webp)
  2. If no settings are provided, the default settings for content-images are used (see below)
  3. If no srcSet is provided, the default from the settings are used (see below)
  4. It will then generate a ResponsivePicture object which you can just show, or do more things with (see below)

Guide Basic

1. Prepare

Always start by getting the IImageService - you will usually just get this once per Razor template:

var imgService = GetService<ToSic.Sxc.Services.IImageService>();

If needed, prepare resize settings using the ResizeSettings(...). This is probably only needed in ca. 10% of all cases, because the defaults are usually what you want to use. If you want to do this, see further explanations further down.

2. Get the Responsive Object

Get the responsive Image or Picture using the Img(...) or Picture(...).

// Example for a file in the App folder
var appIconImg = imgService.Img(App.Path + "/app-icon.png");
var appIconPicture = imgService.Picture(App.Path + "/app-icon.png");
// Example for an image on a dynamic-data object
var blogPicImg = imgService.Img(blogPost.Image);

3. Output

When creating the HTML you have many options. The most basic is just to show the result:

@appIconImg
@appIconPicture

Guide Advanced

Resize Settings

If no settings are provided, the Settings.Images.Content see settings will be used automatically.

The most common scenario is that you have a razor template which shows images that are typically half or a third the size of the normal content. In such a case you would also supply a factor in various possible formats. Here some examples:

var blogPicImgHalf = imgService.Img(blogPost.Image, factor: 0.5);
var blogPicImgThird = imgService.Img(blogPost.Image, factor: "1/3");
var blogPicImg2Thirds = imgService.Img(blogPost.Image, factor: "2:3");

You can also use other settings, like Settings.Images.Screen for larger settings. This can also be combined with factor - here's an example:

var background = imgService.Img(blogPost.Image, settings: Settings.Images.Screen);
var backgroundSmaller = imgService.Img(blogPost.Image, settings: Settings.Images.Screen, factor: 0.9);

You can also use custom settings like this:

var resizeSettings = imgService.ResizeSettings(width: 1000, quality: 75, aspectRatio: "16/9");
var img = imgService.Img(blogPost.Image, settings: resizeSettings);

And you can merge standard settings with your custom settings like this:

var resizeSettings = imgService.ResizeSettings(settings: Settings.Images.Custom, width: 1000, quality: 75, aspectRatio: "16/9");
var img = imgService.Img(blogPost.Image, settings: resizeSettings);

Image alt Description or class Attribute

These are the most common things you may want to specify, so the Img(...) and Picture(...) tag support this in the initial call:

var img = imgService.Img(blogPost.Image, imgAlt: blogPost.Title, imgClass: "some-class-names");

Other attributes can be set as well, but it's more complicated. See custom Output below.

Custom Output

In most cases you'll just want to show the image or picture, like this:

@{
  var img = imgService.Img(blogPost.Image);
  var picture = imgService.Picture(blogPost.Image);
}
@* Now just show them *@
@img
@picture

But you may need to customize more what the output shows. Let's assume you want to give the <img> and <picture> tag a special id here's what you would do:

@{
  var img = imgService.Img(blogPost.Image);
  img.ImgTag.Id("mainImg");
  var picture = imgService.Picture(blogPost.Image);
  picture.ImgTag.Id("mainImg");
  picture.PictureTag.Id("mainPic");
}
@* Now just show them *@
@img
@picture

The img and picture variables are IResponsiveImage and IResponsivePicture objects.

The ImgTag and PictureTag properties are RazorBlade objects and can be customized using the RazorBlade fluid Tag API.

In case you want even more control over your output, you can also piece it together yourself:

@{
  var img = imgService.Img(blogPost.Image);
  var picture = imgService.Picture(blogPost.Image);
}
@* Show the Image with some custom changes *@
@img.Id("imgId").Style("width: 33%")

@* Show your own Image tag *@
<img src="@img.Url" srcset="@img.SrcSet" alt="some alt text">

@* Show the picture with some custom changes on the <picture> *@
@picture.PictureTag.Id("picId")

@* Show the picture with some custom changes on the <picture> and <img> *@
@{
  picture.PictureTag.Id("picId");
  picture.ImgTag.Style("width: 30%");
}
@picture

@* Piece together your own responsive picture tag simple option *@
<picture>
  @picture.SourceTags
  @picture.ImgTag.Style("width: 30%")
</picture>

@* Piece together your own responsive picture tag simple option *@
<picture>
  @picture.SourceTags
  <img src="@picture.Url" style="width: 30%">
</picture>

@* Piece together your own responsive picture tag simple option *@
<picture>
  @foreach(var source in picSet.SourceTags){
    @source.Sizes("some-sizes")
  }
  <img src="@picture.Url" style="width: 30%">
</picture>

TODO: document recipe system

What you Need To Know

  1. The (new) API lies in the namespace ToSic.Sxc.Services - see ToSic.Sxc.Services
  2. The IImageService will do all the magic - see IImageService

History

  1. Introduced in 2sxc 13.01