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.
<img src="/photos/cat.jpg" alt="A grey cat asleep on a windowsill" width="400" height="300" />
Try it
Syntax
<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 getalt=""so assistive technology skips them. - Always give dimensions.
widthandheightas attributes (not only CSS) let the browser reserve space. With CSSmax-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 withfetchPriority="high". onLoadand cached images. If an image is already complete when React attaches handlers (for example during hydration),onLoadmay have fired before. Checkref.current.completein 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. picturefor 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()fromreact-domor a<link rel="preload" as="image">can help.
Related
<a>, SVG elements,<link>- Lessons: JSX in depth, Refs and imperative handles