When to use Image, what each of its options is for, and the choices it leaves to you.
When to use
Image is an <img> with a full-screen viewer, a placeholder while it loads and a fallback when it fails. Use it when you need at least one of those.
Photos people will want to look at closely, like a product shot, a screenshot in a changelog or an uploaded attachment.
Anything user supplied, where the URL can break and a fallback beats a broken image icon.
Anything slow, like a large file or a signed URL, where a placeholder holds the space.
Use something else when
None of those apply. A logo, an illustration or an icon in a table cell wants a plain <img>. With the viewer on, Image adds a clickable wrapper and a tab stop, which a picture nobody clicks does not need.
The picture is a person. Avatar has the shape, the sizes, the initials fallback and the stacking.
People step through a set in place, without a viewer. That is Carousel.
You need Next.js image optimization. That is next/image.
The preview, and turning it off
The viewer is on by default. preview takes false, true or a config object.
Use preview={{ src }} for large files. The thumbnail loads the small file in src, and the viewer loads the full one only when someone opens it.
preview={false} leaves a plain image, with loading and error handling still working. Use it for a logo or an avatar. It also removes the tab stop.
preview.open and preview.onOpenChange control the viewer, so a button, a row action or a shortcut can open it. The thumbnail can be hidden with display: "none".
The viewer locks page scrolling while open, and closes on Esc or a click on the backdrop. preview.mask.closable controls the backdrop click and defaults to true.
preview.cover and preview.mask are different. cover is the overlay on the thumbnail when you hover it, a node or { coverNode, placement }. mask is the backdrop behind the open viewer, a boolean or { enabled, blur, closable }. A node passed to mask still works as the cover, with a deprecation warning.
Placeholder: the loading case
placeholder shows while the image loads, and fallback shows once it fails. placeholder takes two different things.
A node shows until the image loads, then the image replaces it. Use it for a blurred thumbnail, a color block or a skeleton the size of the picture.
A { progress } object shows a progress box instead of the image and never loads src. Render a real <Image> yourself when the file is ready.
You supply the percent.{ progress: { percent } } draws a bar from your state, and { progress: true } animates with no percent and never turns into an image.
Give the box a width and a height either way, so the page does not shift when the image arrives.
Fallback: the broken case
fallback is a URL shown when the image fails to load. Without one you get a broken image icon that says nothing about what was meant to be there.
A data: URI is a safe choice, because it cannot fail to load. A fallback on the server that just failed can fail with it.
Set it once in the image config of ConfigProvider. A fallback on one image still wins over it.
Report failures from onError. The fallback is what the reader sees, and the handler tells you the server is down.
The alt text stays the same when the fallback shows, so write it for the picture you meant to show.
Galleries with Image.PreviewGroup
Image.PreviewGroup gives a set of images one viewer, with previous and next buttons, arrow keys and a counter.
Wrap the images when the page and the viewer show the same set. The layout around them is yours, like a Space or a CSS grid.
Pass items when they differ, like one thumbnail on the page and a whole album in the viewer. It takes URLs or image props objects.
preview.current, preview.onChange and preview.onOpenChange control the group, with the index of the current image.
On a group, preview.mask only takes the backdrop config. A node is a type error there.
The preview toolbar
The open viewer has flip, rotate and zoom controls, plus next and previous arrows in a group. The six toolbar icons come from your icon pack. The two arrows stay Ant Design's.
Your own actionsRender gets the icon pack buttons.info.icons holds the six finished buttons with your pack's glyphs, each with its click handler, disabled state and label. Pick the ones you want and clone one for a new action, since rebuilding them by hand loses state like zoom out being disabled at the smallest scale.
Setting preview.icons has no effect. It type-checks, but the built-in icons override it. Change the toolbar through actionsRender.
preview.scaleStep, preview.minScale (1) and preview.maxScale (50) set the zoom range. preview.movable and preview.wheel turn off dragging and wheel zoom. Turn wheel off where people expect the wheel to scroll the page.
Size, shape and object-fit
Image renders a wrapper around an <img> and puts width and height on both. How the picture fills its box is up to your CSS.
Give every image a width and a height, or an aspect ratio, so the page does not shift when it loads.
Use object-cover for a thumbnail in a fixed frame, where cropping is fine. Use object-contain where the whole picture matters, like a diagram or a screenshot.
Put styles for the picture (fit) on classNames.image and styles for the box (frame, overflow, corners) on classNames.root.
Round the corners with rounded-lg or rounded-full on classNames.root, which reaches the image, the hover cover and the placeholder. On className it rounds only the image, and the cover stays square. There is no shape prop.
Lazy loading
Image passes loading="lazy" to the <img>, as it does any image attribute.
Use it below the fold and on every item in a long gallery. Leave it off the main image of the page, or it loads late.
Size the box in advance, so the browser can tell what is near the viewport.
placeholder and loading="lazy" work together: one holds the space, the other delays the request.
decoding="async" and fetchPriority pass through the same way.