Responsive Image

OsirionResponsiveImage renders an <img> that keeps its space while it loads, offers the browser files sized for the screen, and loads lazily unless it is the page's main image. It is plain HTML, so it needs no script.

Available from 4.1.

Usage

@using Osirion.Blazor.Components

<OsirionResponsiveImage Src="/images/team.jpg" Alt="The team at the 2026 meetup" Width="1200" Height="800" />

This renders a lazily loaded, asynchronously decoded image with width and height, so the browser reserves its space before the file arrives.

With an image service or CDN that resizes on request, give the widths to offer and how to build each file's URL:

<OsirionResponsiveImage Src="@PhotoAt(1600)"
                        Alt="A laptop showing charts on a desk"
                        Width="1600"
                        Height="1066"
                        Widths="imageWidths"
                        SrcFormatter="(_, width) => PhotoAt(width)"
                        Sizes="(min-width: 992px) 720px, 100vw"
                        Priority="true"
                        Caption="Monthly figures for the second quarter." />

@code {
    private readonly int[] imageWidths = [640, 960, 1280, 1600];

    private static string PhotoAt(int width) =>
        $"https://images.example.com/laptop.jpg?w={width}&h={width * 2 / 3}&fit=crop";
}

The srcset becomes four candidates from 640 to 1600 pixels wide. Priority marks this as the main image of the page, so it loads at once instead of lazily. images.example.com stands for your own image service.

Parameters

Unmatched attributes go on the <img>, not on the <figure>.

When there is a srcset and Sizes is not set, lazily loaded images get sizes="auto, 100vw" (the browser uses the laid-out width where it supports auto) and priority images get 100vw. Without a srcset, no sizes attribute is written.

Behavior

• Every image gets decoding="async". Without Priority it also gets loading="lazy"; with Priority it gets loading="eager" and fetchpriority="high". Mark only one image per page as Priority, the one in the first view: lazy loading that image would delay Largest Contentful Paint.
• Widths are sorted, duplicates and values of zero or less are dropped. If nothing is left, no srcset is written.
• Every file in the srcset should have the aspect ratio of Width and Height. The stylesheet sets height: auto and max-width: 100%, so the image scales down inside its container and keeps that ratio.
• Width or Height set to zero or a negative number throws ArgumentOutOfRangeException.
• URLs are written as attributes, so Razor encodes them. The component does not check where they point; pass URLs you control or have validated.

Styling

The figure's bottom margin uses --osirion-spacing-4, and the caption uses --osirion-spacing-2, --osirion-font-size-sm and --osirion-text-secondary, each with a fallback value.

Related

• Video embed
• Content components