Images and alt text

An img element needs two attributes to be useful: src, which says where the picture is, and alt, which says what it shows when it cannot be seen.

The img element

Pictures are not stored inside the HTML file. The page points to them, and the browser fetches each one as a separate file. The <img> element does the pointing. It is a void element, so it has no closing tag, and its src attribute holds the address of the image, absolute or relative, just like the href of a link. Images are replaced elements: the browser replaces the element with the picture, and the picture decides how big it is unless you say otherwise.

<img src="images/sourdough.jpg"
     alt="A round sourdough loaf with a dark, cracked crust"
     width="400" height="300">

The width and height attributes give the size of the image in pixels, without a unit. Set them to the real size of the file. The HTML usually arrives before the pictures, so without these numbers the browser lays out the text first and then pushes it down when each image finishes loading, which is jarring if you have started reading. With them, the browser reserves the right space from the start. To show an image smaller or larger, use CSS rather than changing these numbers.

Writing alt text

The alt attribute holds a text alternative. A screen reader reads it aloud, a browser shows it when the file fails to load, and search engines read it to understand the picture. MDN suggests a simple test: what would be lost if the image did not show up? Write that, briefly. For a photo of a product, describe what someone would need to know to choose it. For a chart, give the point the chart makes, such as Sales tripled from January to March, rather than Bar chart.

• Do not start with Image of or Picture of. Screen readers already announce that it is an image.
• Decorative images, such as a wavy divider line, get an empty alt="". Then screen readers skip them. Leaving alt out entirely is different: some screen readers read the file name instead.
• If an image is the only content of a link, its alt text is the link text, so describe where the link goes (Home), not the picture (Bread logo).
• If the same information is already in the text next to the image, alt="" avoids saying it twice.

Figures and captions

When an image comes with a caption, wrap both in <figure> and put the caption in <figcaption>. This ties the caption to the image for assistive technology, which a plain paragraph under the image does not do. A caption and alt text have different jobs: the caption is read by everyone, while alt replaces the image when it is missing. They should not simply repeat each other. A figure does not have to hold a picture; a code sample, a table or a poem can be a figure too.

Formats, data URLs and inline SVG

Photographs are usually JPEG or WebP, flat graphics with sharp edges are PNG, and drawings made of shapes are often SVG, a text format that stays sharp at any size. A small image can even be written straight into the src as a data URL that starts with data:image/svg+xml,; the exercises below use this so nothing loads from another site. An SVG can also be written directly in the HTML with an <svg> element. Give it role="img" and a <title> child so screen readers have a name for it. Finally, loading="lazy" on images far down a long page tells the browser to wait until the reader scrolls near them.

One more rule from MDN: only use images you have the right to use. Pictures you find online are protected by copyright unless their licence says otherwise, and pointing your src at someone else's server without permission, called hotlinking, also makes them pay for your traffic.