Our.Umbraco.Slimsy
6.0.1
dotnet add package Our.Umbraco.Slimsy --version 6.0.1
NuGet\Install-Package Our.Umbraco.Slimsy -Version 6.0.1
<PackageReference Include="Our.Umbraco.Slimsy" Version="6.0.1" />
paket add Our.Umbraco.Slimsy --version 6.0.1
#r "nuget: Our.Umbraco.Slimsy, 6.0.1"
// Install Our.Umbraco.Slimsy as a Cake Addin #addin nuget:?package=Our.Umbraco.Slimsy&version=6.0.1 // Install Our.Umbraco.Slimsy as a Cake Tool #tool nuget:?package=Our.Umbraco.Slimsy&version=6.0.1
Slimsy
Effortless Responsive & Lazy Images with LazySizes and Umbraco
Slimsy v6 is made for Umbraco v14+!
Slimsy v5 is made for Umbraco v13.2 < v14!
Slimsy v4 is made for Umbraco v10, v11 & v12!
Release Downloads
Prerelease Downloads
Installation
1. Install from NuGet
2. Add .AddSlimsy()
to program.cs before the call to the .Build()
method
e.g.
builder.CreateUmbracoBuilder()
.AddBackOffice()
.AddWebsite()
.AddDeliveryApi()
.AddComposers()
.AddSlimsy()
.Build();
3. Add to _ViewImports.cshtml
@using Slimsy.Enums;
@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.
img {
display:block;
}
If you are using LQIP then you will also need to ensure img elements are set to width:100%;
e.g.
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
<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.
<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
private readonly SlimsyService _slimsyService;
public ResponsiveImageViewComponent(SlimsyService slimsyService)
{
_slimsyService = slimsyService;
}
7 (optional). Adjust the rendering of your TinyMce Richtext editors
<div class="col-md-9">
<article>
@SlimsyService.ConvertImgToResponsive(Model, "richTextBody", renderPicture:true, pictureSources: new []{"webp"})
</article>
</div>
8 (optional). Adjust the renderer of media within the Grid editor
There's quite a lot to this - so check it out in the demo site here
Options
Add/Edit appsettings.json
"Slimsy": {
"WidthStep": 180,
"UseCropAsSrc": false,
"DefaultQuality": 70,
"Format": "",
"BackgroundColor": "",
"AppendSourceDimensions": true,
"EncodeCommas": true,
"AutoOrient": true
}
or edit Startup.cs
to modify SlimsyOptions
.AddSlimsy(options =>
{
options.DefaultQuality = 60;
options.WidthStep = 60;
options.UseCropAsSrc = true;
})
TagHelper also has some options in appsettings.json
(available in v4.1+)
- 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.
"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 rendersrole="presentation"
on theimg
tagfetch-priority
which renders on theimg
tag, for examplefetchpriority="high"
image-crop-mode
specifies a crop mode such as "Pad"image-crop-anchor
used with crop-mode to set where cropping should be focussedloading
(available v4.2+) you can set toEager
to not lazy load, useful for optimzing LCP on the first image rendered on the page
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
.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.
"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
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 which is MIT licensed.
Without the amazing ImageSharp this package wouldn't exist, so many thanks go to James and all the SixLabors team for creating ImageSharp!
Many thanks to Douglas Robar for naming Slimsy.
Change log
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Umbraco.Cms.Web.Common (>= 14.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
6.0.1 | 174 | 7/25/2024 |
6.0.0 | 167 | 5/30/2024 |
6.0.0-beta2 | 91 | 5/8/2024 |
6.0.0-beta1 | 83 | 4/18/2024 |
5.1.2 | 3,325 | 5/8/2024 |
5.1.1 | 1,052 | 4/3/2024 |
5.1.0 | 967 | 3/18/2024 |
5.0.0 | 1,805 | 3/8/2024 |
4.2.1 | 595 | 4/4/2024 |
4.2.0 | 220 | 3/18/2024 |
4.1.0 | 11,252 | 9/22/2023 |
4.1.0-beta4 | 3,278 | 8/9/2023 |
4.1.0-beta3 | 1,007 | 7/20/2023 |
4.1.0-beta2 | 792 | 7/13/2023 |
4.1.0-beta1 | 634 | 6/29/2023 |
4.0.3 | 9,435 | 4/5/2023 |
4.0.2 | 7,615 | 11/25/2022 |
4.0.1 | 818 | 11/21/2022 |
4.0.0 | 8,705 | 9/20/2022 |
4.0.0-beta1 | 712 | 8/3/2022 |
3.0.0 | 39,775 | 5/22/2020 |
3.0.0-beta5 | 1,354 | 5/14/2020 |
3.0.0-beta4 | 928 | 4/9/2020 |
3.0.0-beta3 | 4,675 | 10/15/2019 |
3.0.0-beta2 | 2,399 | 7/29/2019 |
3.0.0-beta1 | 4,799 | 4/2/2019 |
2.1.0-beta2 | 5,206 | 10/3/2018 |
2.1.0-beta1 | 1,171 | 10/2/2018 |
2.0.0 | 23,732 | 4/27/2018 |
2.0.0-beta4 | 1,523 | 3/14/2018 |
2.0.0-beta3 | 2,335 | 1/5/2018 |
2.0.0-beta2 | 1,661 | 10/31/2017 |
2.0.0-beta1 | 1,294 | 10/25/2017 |
1.1.7 | 36,385 | 2/3/2016 |
1.1.6 | 3,373 | 11/3/2015 |
1.1.4 | 8,138 | 2/26/2015 |