Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Built-in DOM Components

The React img element

Reference for the React img element: always set alt, use srcSet and sizes for responsive images, lazy load below the fold and handle onLoad and onError.

<img> shows an image. Its attributes are the HTML ones with React's camelCase spelling where the DOM property is camelCase: srcSet, crossOrigin, fetchPriority, referrerPolicy. The element is void, so in JSX it must be self-closed: <img ... />.

Three things matter for almost every image: a meaningful alt text for accessibility, explicit width and height so the browser reserves space before the file arrives (this avoids layout shift), and loading="lazy" for images far below the first screen.

JSX
<img src="/photos/cat.jpg" alt="A grey cat asleep on a windowsill" width="400" height="300" />

Try it

Alt text, size and onLoad
Responsive attributes in the DOM

Syntax

JSX
<img
  src="url"
  alt="description"
  width={number | string}
  height={number | string}
  srcSet="small.jpg 480w, large.jpg 1200w"
  sizes="(max-width: 600px) 100vw, 600px"
  loading="lazy | eager"
/>
Name Description
src The image URL. A data URL works too.
alt Text alternative. Required in practice. Use alt="" for purely decorative images.
width, height Intrinsic size in pixels (numbers or strings without units). Together they give the aspect ratio.
srcSet, sizes Candidate files and the slot width, so the browser picks the best file.
loading lazy delays loading until near the viewport; eager (default) loads at once.
decoding async, sync or auto.
fetchPriority high, low or auto. Use high for the main hero image.
crossOrigin, referrerPolicy CORS and referrer settings.
onLoad, onError Called when the file loads or fails.

Returns: an HTMLImageElement.

Edge cases: a missing alt is not a React error, but it is an accessibility bug. If src changes, the browser loads the new file and fires onLoad again. An empty string src is ignored by React 19 with a warning, because an empty source would make the browser request the page itself.

Usage notes

  • Always give alt. Describe what the image says, not "image of". Decorative images get alt="" so assistive technology skips them.
  • Always give dimensions. width and height as attributes (not only CSS) let the browser reserve space. With CSS max-width: 100%; height: auto; the image still scales.
  • Do not lazy load the main image. The first large image on the page (often the LCP element) should be eager, possibly with fetchPriority="high".
  • onLoad and cached images. If an image is already complete when React attaches handlers (for example during hydration), onLoad may have fired before. Check ref.current.complete in an effect when you depend on the event.
  • Fallbacks. In onError, switch to a placeholder with state. Guard against loops: if the placeholder also fails, stop.
  • picture for art direction. Use <picture> with <source media> when you need different crops, not only different sizes.
  • Bundlers. Importing an image (import cat from './cat.jpg') gives a URL string in most setups. That is a bundler feature, not React.
  • Prefer hints in head. To start loading a critical image early, preload() from react-dom or a <link rel="preload" as="image"> can help.