Skip to content

Image

An image with a placeholder while it loads and a fallback when it fails.

A gradient from light to dark blue

Installation

  1. Add the registryOnce per project
  2. 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.

A gradient from yellow to redA gradient from pale to deep greenA gradient from pink to crimson

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.

The team at the offsiteThe team at the offsite

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.

components/app-image.tsx

A fill image positions itself in its parent, so place it in an Aspect Ratio.

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.

Image