Images, media and responsive crops in Umbraco

How Umbraco handles images

Images live in the Media section. Umbraco resizes them on the fly with ImageSharp: add ?width=800 to an image URL and you get an 800px-wide version, cached after the first request. Crops let editors choose the focal point for each shape you need.

Step 1: Add alt text to images

Alt text matters for accessibility and SEO, so make editors add it:

1. Go to Settings › Media Types › Image.
2. Add a Textstring property called Alt text with the alias altText, and make it mandatory.

Step 2: Define crops

1. Go to Settings › Data Types › Image Cropper.
2. Add a crop called hero at 1600 × 900, and another called square at 600 × 600.
3. Editors can now drag the focal point and adjust each crop in the Media section.

Step 3: Pick images on a page

Add a Media Picker property, for example Hero image with the alias heroImage, to your document type. Limit it to the Image media type and to a single item.

Step 4: Output a responsive image

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Cms.Core.Models.MediaWithCrops>
@{
    var alt = Model.Value<string>("altText") ?? "";
    int[] widths = [480, 800, 1200, 1600];
}
<img src="@Model.GetCropUrl("hero")"
     srcset="@string.Join(", ", widths.Select(w => $"{Model.GetCropUrl(width: w, height: w * 9 / 16, furtherOptions: "&format=webp")} {w}w"))"
     sizes="(max-width: 800px) 100vw, 800px"
     alt="@alt" loading="lazy" width="1600" height="900">

Use it from any template:

@if (Model.Value<Umbraco.Cms.Core.Models.MediaWithCrops>("heroImage") is { } hero)
{
    @await Html.PartialAsync("ResponsiveImage", hero)
}

• GetCropUrl("hero") uses the crop and focal point the editor chose.
• GetCropUrl(width: 800) resizes to a width without a named crop.
• furtherOptions: "&format=webp" serves smaller WebP files.
• width, height and loading="lazy" prevent layout shift and speed up the page.

Useful image URL options

/media/abc123/photo.jpg?width=800                     resize to 800px wide
/media/abc123/photo.jpg?width=600&height=600&rmode=crop  crop to a square
/media/abc123/photo.jpg?width=800&format=webp&quality=80 smaller WebP

Tips

• Upload images at a sensible size, around 2,500px at most. ImageSharp makes them smaller, but can't add detail.
• Processed images are cached on disk after the first request, so resizing only happens once. On load-balanced hosting, use shared storage such as Azure Blob Storage for media.