- Add the registry
- Add image
Usage
Image renders an <img>. It fills its box with the layer-1 color until the image loads, and draws
a faint edge so a light image stands out from a light page. Pass outline-0 to remove the edge,
such as for a logo with a transparent background.
alt is required. Describe what the image shows, or pass an empty string for an image that's only
decoration, so screen readers skip it. Images load lazily, so the browser fetches them only as they
near the viewport. Pass loading="eager" for an image at the top of the page.
Pass draggable={false} so someone can't drag the image out of the page. A
Carousel already keeps a mouse drag from picking up its images.
The image sets data-loading while it loads and data-loaded once it has, for your own styles.
Examples
Sizing
Give an image width and height, or an aspect ratio class such as aspect-video, so the page
reserves its space before it loads. Add object-cover to crop an image to that shape rather than
stretch it.
Fallback
An image that fails to load becomes an icon in the same box, with data-error. Pass fallback to
show something else. Screen readers still announce the alt text.


Loading state
An <img> can't hold other elements, so place a Skeleton or
Spinner beside the image to show while it loads. Mark the image as a peer,
and give the overlay hidden and peer-data-loading:block.
Image sets data-loading only after it hydrates, and only on an image that's still loading. So the
overlay never covers an image that loaded before the page became interactive. It also disappears
when the image fails, so the fallback shows. To show a Spinner instead, center it with
absolute inset-0 m-auto.
Frameworks
To optimize images with your framework, pass its image component to render. Image merges its
class names, attributes and load handlers into the framework's <img>. It leaves loading and
decoding to the framework's component.
Wrap Image once with next/image, which takes the image's src, sizes and loading options.
A fill image positions itself in its parent, so place it in an
Aspect Ratio.
Unpic (opens in a new tab) resizes images through your image CDN. Wrap Image once with its
Image.
Unpic (opens in a new tab) resizes images through your image CDN. Wrap Image once with its
Image.
Props
Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.