KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #claude-code #codex #cli #agent-skills #ai #dsh-plugin #mcp #windows #agent

Slimsy

★ 73 Open GitHub ↗

Effortless Responsive & Lazy Images with LazySizes and Umbraco

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Slimsy
============
**Effortless Responsive & Lazy Images with LazySizes and Umbraco**

# Slimsy v7 is made for Umbraco v17 & v18 (v7.1.1+)!
# Slimsy v6 is made for Umbraco v14, v15 & v16 (it does also work with v17)!
# Slimsy v5 is made for Umbraco v13.2 < v14!
# Slimsy v4 is made for Umbraco v10, v11 & v12!

![](https://raw.githubusercontent.com/Jeavon/Slimsy/main-v7/Slimsy.png)

__Release Downloads__

NuGet Package: [![NuGet release](https://img.shields.io/nuget/vpre/Our.Umbraco.Slimsy.svg)](https://www.nuget.org/packages/Our.Umbraco.Slimsy/)

__Prerelease Downloads__

NuGet Package: [![MyGet build](https://img.shields.io/myget/umbraco-packages/vpre/Our.Umbraco.Slimsy.svg)](https://www.myget.org/feed/umbraco-packages/package/nuget/Our.Umbraco.Slimsy)

[![CI Build](https://github.com/Jeavon/Slimsy/actions/workflows/ci.yml/badge.svg?branch=dev-v7)](https://github.com/Jeavon/Slimsy/actions/workflows/ci.yml)

## Installation

### 1. Install from NuGet

### 2. Add `.AddSlimsy()` to program.cs before the call to the `.Build()` method

e.g.
```c#
builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .AddSlimsy()
    .Build();
```
### 3. Add to _ViewImports.cshtml

```c#
@using Slimsy.Enums
@using Slimsy.Extensions
@addTagHelper *, Slimsy
@inject Slimsy.Services.SlimsyService SlimsyService
```

### 4. Add lazysizes.min.js & to your templates/views

In your template add the JavaScript files

```
<script src="/scripts/lazysizes.min.js" async=""></script>
```

### 5. Ensure all img elements are set to `display: block` or `display: inline-block;`

e.g.

```css
img {
    display:block;
}
```

If you are using LQIP then you will also need to ensure img elements are set to `width:100%;`

e.g.

```css
img {
    display:block;
    width:100%;
}
```

### 6. Use the `<slimsy-picture>` tag helper or manually adjust your image elements, adding `data-srcset`, `data-src`, `sizes="auto"` & `class="lazyload"` attributes

```HTML+Razor
<slimsy-picture media-item="@person.Photo" width="323" height="300" css-class="myClass" render-lqip="true" render-webp-alternative="true"></slimsy-picture>
```

Use the `GetSrcSetUrls` UrlHelper extension methods to generate your `data-srcset` attributes. For these methods to function correctly your image property types should use the built-in **Image Cropper**.

```HTML+Razor
<div class="employee-grid__item__image">
    <img data-srcset="@Url.GetSrcSetUrls(person.Photo, 323, 300)" srcset="@Url.GetSrcSetUrls(person.Photo, 250, 250, quality: 40)" data-sizes="auto" class="lazyload"/>
</div>
```

Or inject SlimsyService into your ViewComponents

```C#
private readonly SlimsyService _slimsyService;
public ResponsiveImageViewComponent(SlimsyService slimsyService)
{
	_slimsyService = slimsyService;
}
```

### 7 (optional). Adjust the rendering of your Richtext editors

e.g.

```HTML+Razor
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem>
@{
    var slimsyDefaultPictureSources = SlimsyOptions.Value.TagHelper.DefaultPictureSources.Select(x => x.Extension).ToArray();
}
<div style="padding: 20px">
    @Html.ConvertImgToResponsive(Model.Content, "richText", renderPicture: true, pictureSources: slimsyDefaultPictureSources)
</div>
```

### 8 (optional). Adjust the renderer of media within the Block Grid editor

e.g.

```HTML+Razor
@using Umbraco.Cms.Core
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.Blocks.BlockGridItem>
@{
    var typedMediaPickerSingle = Model.Content.Value<Umbraco.Cms.Core.Models.MediaWithCrops>("image");
    if (typedMediaPickerSingle != null)
    {
        var sourceWidth = typedMediaPickerSingle.Value<int>(Constants.Conventions.Media.Width);
        var sourceHeight = typedMediaPickerSingle.Value<int>(Constants.Conventions.Media.Height);

<slimsy-picture media-item="@typedMediaPickerSingle" width="sourceWidth" height="sourceHeight" css-class="object-fit:cover; width:100%; height:100%;" render-lqip="true"></slimsy-picture>

} else {
        <p>Missing image</p>
    }
}
```

# Options

Add/Edit `appsettings.json`

```json
  "Slimsy": {
    "WidthStep": 180,
    "UseCropAsSrc": false,
    "DefaultQuality": 70,
    "Format": "",
    "BackgroundColor": "",
    "AppendSourceDimensions": true,
    "EncodeCommas": true,
    "AutoOrient": true
  }
```

or edit `Startup.cs` to modify SlimsyOptions
```c#
.AddSlimsy(options =>
{
    options.DefaultQuality = 60;
    options.WidthStep = 60;
    options.UseCropAsSrc = true;
})
```

TagHelper also has some options in `appsettings.json`

- SingleSources - allows specific file extensions to only render a single source
- DefaultPictureSources - allows multiple picture sources to be defined, example below is for both avif and webp formats
- ImageDimensions - defines if width and height attributes should be rendered on the `img` tag

e.g.

```json
  "Slimsy": {
    "WidthStep": 180,
    "UseCropAsSrc": true,
    "DefaultQuality": 70,
    "TagHelper": {
      "SingleSources": [ "gif" ],
      "DefaultPictureSources": [
        {
          "Extension": "avif",
          "Quality": 60
        },
        {
          "Extension": "webp",
          "Quality": 70
        }
      ],
      "ImageDimensions": true
    }
  }
```

TagHelper has new parameters

- `decorative` which renders `role="presentation"` on the `img` tag
- `fetch-priority` which renders on the `img` tag, for example `fetchpriority="high"`
- `image-crop-mode` specifies a crop mode such as "Pad"
- `image-crop-anchor` used with crop-mode to set where cropping should be focussed
- `loading` you can set to `Eager` to not lazy load, useful for optimzing LCP on the first image rendered on the page
- `mobile-crop-alias` allows you to specify a separate crop to use for mobile/smaller viewports

## Mobile Crop Support

The `<slimsy-picture>` tag helper supports separate mobile crops for responsive images. When you specify both `crop-alias` and `mobile-crop-alias`, Slimsy will:

1. Generate mobile-optimized sources for smaller viewports using the mobile crop
2. Generate desktop sources for larger viewports using the main crop
3. Automatically apply media queries to serve the appropriate source based on viewport width

The mobile width threshold can be configured in `appsettings.json` (<em>it will default to 720 if not specified in the settings</em>):

```json
"Slimsy": {
  "MobileWidth": 720
}
```

### Example Usage

```HTML+Razor
<slimsy-picture 
    media-item="@Model.HeroImage" 
    crop-alias="desktop" 
    mobile-crop-alias="mobile" 
    css-class="hero-image" 
    render-lqip="true">
</slimsy-picture>
```

This will generate:
- Mobile sources using the "mobile" crop for viewports up to the configured mobile width (default 720px)
- Desktop sources using the "desktop" crop for larger viewports
- Appropriate media queries to serve the correct image based on screen size

# How to use AVIF format in v4.1+

There is not currently a AVIF encoder for ImageSharp, keep an eye on https://github.com/hey-red/ImageSharp.Heif which has amditions of adding a encoder in the future.

Cloudflare Image Resizing does support AVIF encoding and this can be used by Slimsy.

### 1. Install the CloudflareImageUrlGenerator package

See https://github.com/Jeavon/CloudflareImageUrlGenerator for full details.

```
dotnet add package Umbraco.Community.CloudflareImageUrlGenerator
```

### 2. Add to Startup.cs in the ConfigureServices method

```c#
.AddCloudflareImageUrlGenerator()
```

### 3. Enable Image Resizing on Cloudflare

https://developers.cloudflare.com/images/image-resizing/enable-image-resizing/

### 4. Set the avif format as a DefaultPictureSources and enable AppendSourceDimensions in appsettings.json

e.g.

```json
  "Slimsy": {
    "AppendSourceDimensions": true,
    "TagHelper": {
      "DefaultPictureSources": [
        {
          "Extension": "avif",
          "Quality": 60
        },
        {
          "Extension": "webp",
          "Quality": 70
        }
      ]
    }
  }
```

### 5. Check the rendered sources

Image paths for avif and webp should begin with `/cdn-cgi/image/format=avif,quality=70`

# Lazysizes.js

Lazysizes.js is awesome and it's part of what makes Slimsy so easy to implement. If you need to find out more information about it or how to hook into it's Javascript events be sure to check out it's [GitHub](https://github.com/aFarkas/lazysizes)

# Test Site & Source Code

A test site is included in the solution, the username and password for Umbraco are `admin@admin.com/password1234567890`

# Credits and references

This project includes [LazySizes](https://github.com/aFarkas/lazysizes) 
which is MIT licensed.

Without the amazing [ImageSharp](https://github.com/SixLabors/ImageSharp) this package wouldn't exist, so many thanks go to [James](https://github.com/JimBobSquarePants) and all the [SixLabors](https://github.com/SixLabors) team for creating  ImageSharp!

Many thanks to Douglas Robar for naming Slimsy.

# Change log

[Here](https://github.com/Jeavon/Slimsy/blob/dev-v7/Changelog.md)

Slimsy

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README