How to Use the img Element

The HTML img element displays an image in a page. Write alt text that explains the image's role so the page still communicates when the image cannot be seen or loaded.

The answer first

Minimal example

<img src="/images/mountain.jpg"
     alt="A mountain and lake at sunset"
     width="1200"
     height="800">

width and height help the browser reserve an appropriate area before the image arrives. Keep their aspect ratio consistent with the image, even when CSS changes the rendered size.

Match alt text to the image's role

alt is not only an error message for a failed image request. It is the text alternative for people who cannot process the image or who have disabled image loading.

Image role	How to write alt
Informative image	Briefly state the important content, for example alt="A mountain and lake at sunset"
Decorative image	Use alt="" so assistive technology can treat it as unnecessary content
Image inside a link	Describe the purpose of the destination, not just the pixels in the image
Image containing text	Provide the meaningful text from the image in the alternative

Whether an alt value can be omitted depends on the image's role and surrounding context. Check whether someone can accomplish the same task when the image is unavailable.

Choose an image candidate for the display

Sending one very large file to every screen can waste bandwidth. Use srcset for candidates and sizes to describe how wide the image is expected to be in the layout.

<img
  src="/images/article-800.jpg"
  srcset="/images/article-400.jpg 400w,
          /images/article-800.jpg 800w,
          /images/article-1600.jpg 1600w"
  sizes="(max-width: 600px) 100vw, 800px"
  alt="A landscape illustrating the article"
  width="1600"
  height="900">

Candidate selection can consider the display slot, pixel density, and other conditions. Adding srcset does not mean the browser will always choose the smallest or largest file.

Loading and display hints

• loading="lazy" is a hint to defer an image that is not immediately needed. Do not apply it mechanically to the important image at the top of every page.
• decoding="async" and related values are hints about image decoding. They do not fix every ordering detail of rendering.
• fetchpriority is a hint about fetch priority. Giving high priority to many images can compete with more important resources.
• Providing width and height can make the layout more stable before the image loads.

Common mistakes

• Writing alt="image" or a filename instead of explaining the image's role.
• Adding a description to a decorative image and making assistive technology read unnecessary content.
• Omitting alt and leaving the image's meaning to visual context alone.
• Using width and height with a different aspect ratio from the actual image.
• Trying to solve meaning and accessibility with loading or fetchpriority alone.

Check it in Atlas

For alternative text and accessibility mappings, srcset and sizes selection, intrinsic dimensions, loading and decoding behavior, and implementation evidence, see img in Yugien Atlas. To link places inside an image, see How to use an image map. For changing image compositions or formats by display condition, also see the picture element page.

For drawing or processing images with JavaScript, see How to Use the canvas Element.