Image

An image needs a Src and an Alt: the source is the file, and the alternate text is what the image says to anyone who cannot see it. The attribute is always rendered, so an image given no text at all is announced as decorative rather than read out as a file name - which means a decorative image is one whose Alt is deliberately left empty, not one that forgot it. With nothing else set, the frame takes the natural size of the image, and the image stays hidden until it has loaded. Title is the tooltip a mouse gets on hover - an aside rather than a place for anything the image cannot do without, since a touch screen never shows it.

A disabled image keeps its colors and dims, and stops answering the pointer.

Width and Height size the frame. A bare number is read as a pixel count and anything else is used as written, so any CSS length works - 9rem, 50%, calc(100vw - 2rem). Given only one of the two, the image scales along the other one and keeps its aspect ratio; given both, the frame is exactly that size and the image is left to overflow it unless an ImageFit says what to do instead. The backgrounds below are there to show the frame itself.

AspectRatio gives the frame a shape instead of a second measurement: a width and a ratio are enough, and the height follows. It is what reserves the room the image will need before it has arrived, so the content below it is not pushed down the moment it does - the layout shift a page is measured by. It pairs with ImageFit, which decides what the image does inside a frame whose shape is not its own.

ImageFit settles what happens once the image and the frame turn out to be different shapes. None leaves both alone and crops whatever does not fit from the right and the bottom; Center does the same but crops around the middle. Contain fits all of the image inside the frame and leaves the rest of the frame empty, Cover fills the frame and crops the overflow, Fill stretches the image to the frame exactly and distorts it, and ScaleDown is Contain that never enlarges a small image. CenterContain and CenterCover are the two centered variants that scale along the one axis Cover (the parameter) names.

A fit that crops has to crop somewhere, and by default that is around the middle of the image - which is the wrong half of a photograph whose subject is not there. ImagePosition is the CSS object-position of the image: a keyword pair (top, bottom right) or two lengths or percentages. It only has an effect where something is actually cropped, so it goes with Cover and with a frame narrower or shorter than the image.

Cover is read by the two centered fits alone, and it names the axis they scale along. It describes the shape of the frame rather than of the image: Landscape for a wide frame, where the image is shown at the full height and the width follows, and Portrait - the default - for a tall one, where it is the width that is filled. The other fits are expressed with object-fit, which reads both shapes on its own and needs no such hint.

MaximizeFrame hands the sizing over to whatever is around the component: the frame takes the full width and height of its parent, and the image covers it. An explicit ImageFit still has the last word over that cover, so the same maximized frame can just as well contain the image instead of cropping it.

The frame is what carries the shape, and it clips - so Rounded and Circular crop the image rather than merely rounding a box drawn around it. Rounded takes the theme's surface radius, which makes it follow the design system rather than a number written here; Circular is only a circle while the frame is a square, so it goes with an AspectRatio of 1 and a Cover fit. Bordered draws the theme's border around it, inside the frame's own size, and Shadow lifts it off the surface with the same elevation every other raised surface of the library has. All four read the theme, so they follow a design system rather than a number written on the page.

The component follows the browser's own load and error events, and the resulting BitImageState decides what is on screen: LoadingTemplate stands in the frame while the image is on its way and ErrorTemplate once it has failed, and OnLoadingStateChange reports every transition - including the return to Loading when the source changes. LoadingState is the same value read off the component, and ReloadAsync asks for the image again from the beginning, which is the answer to a failure that was the network's rather than the image's: it replaces the img element instead of patching it, so the browser really does fetch a source it already holds an answer for.

FallbackSrc is the other answer to a failure: instead of a template, another image. It is tried exactly once - a fallback that fails as well leaves the component in the error state rather than asking for it again - and it is also what is shown when no Src is given at all, which makes a missing avatar and a broken one look the same. A fallback belongs to the page rather than to the network: something already cached or inlined as a data URI, since whatever kept the first image away may well keep this one away too.

PlaceholderSrc is the blur-up placeholder: a tiny, heavily compressed stand-in - normally the same picture at a few dozen pixels, inlined as a data URI so it costs no request - which fills the frame from the first frame and is taken away the moment the real image arrives. It fills the frame, so it needs a frame with a size: a Width and a Height, an AspectRatio, or a MaximizeFrame. Paired with FadeIn it is the whole of the progressive-image effect, with no layout shift at either end.

The image is hidden until it has loaded, which keeps a half-drawn or broken one off the page at the cost of the frame collapsing while it waits. StartVisible is the other trade: the image is shown from the start - the browser's own progressive rendering - and hidden only if it fails. FadeIn animates the moment the image becomes visible rather than the mounting of the component, so it is the arrival that is animated; it collapses to nothing under prefers-reduced-motion unless ForceAnimation says otherwise.

What the browser decides for itself stays the browser's. Loading is the loading attribute: a Lazy image is only fetched once the browser expects it to be needed, so it keeps the room it will take up while it waits - give it a Height or an AspectRatio so that room is the right size - and it is never right for what is already on the first screen. FetchPriority reorders one image against everything else being fetched, which is worth setting on exactly two kinds: the largest thing on the first screen, and the decorative ones far below that should not compete with it. Decoding hints at whether the pixels may be produced off the critical path. CrossOrigin and ReferrerPolicy cover the two things a cross-origin image needs to settle - whether its pixels may be read back, and how much of the current address is handed to whoever serves it - and anything else an img accepts goes through ImageAttributes, which is merged with what the parameters set rather than replaced by it.

Srcset hands the browser a list of the same picture at different sizes, each tagged with its width (480w) or its pixel density (2x), and lets it choose - a decision the page cannot make, since only the browser knows the screen and the network. Sizes is what makes a width-descriptor list usable: it says how wide the image will be laid out before the layout is known, and without it the browser assumes the full width of the viewport and over-fetches accordingly. Src stays as the answer for anything that reads neither.

Srcset answers "how many pixels"; Sources answers the two questions it cannot. The first is art direction - a different crop of the subject at a different viewport, a wide hero on a desktop and a square one on a phone - which is a decision about the composition rather than about the file size. The second is format: an AVIF and a WebP offered ahead of the JPEG that every browser understands, each with its Type, so a browser that cannot read one skips it without fetching anything. The browser walks the list in order and takes the first it is satisfied by, which makes the order the priority, and Src stays the answer that is always understood. The image is wrapped in a picture that lays nothing out of its own, so the frame, the fit and the shape are untouched.

Assigning OnClick makes the image a button rather than a picture: it becomes focusable, is announced as a button whose name is the Alt - so the text says what the click does rather than what the image shows - and answers the Enter and the Space keys as well as the pointer. A disabled image answers neither. Draggable is worth setting to false on a clickable image, since a browser makes an image draggable of itself and a press that was meant as a click can start a drag instead.

ChildContent is a layer over the image, filling the frame: a caption, a badge, a gradient scrim, a play button. It is laid over the whole frame, so it needs a frame with a size, and it is the last thing in it, which is what puts it above the image without either of them needing a z-index.

Style and Class reach the frame, which is the element that carries the size and the shape, and Styles and Classes reach each part of the component by name - the Root frame, the Image itself, the Placeholder, the two template wrappers and the Content overlay. A filter, a mask or a transition belongs on the image; a shadow or a margin belongs on the frame.

An image has no reading direction of its own - it is a picture, not a run of text - so Dir changes nothing about how it is drawn. What it does change is the direction the content of the component flows in: a caption laid over the image, a loading or error template, and the placement of the frame within whatever lays it out. The direction is also cascaded, so a BitImage inside an RTL container inherits it.