HTML Images and Alt Text

The <img> element embeds an image in a page. It’s a void element, no closing tag and no content between tags.

<img src="cat.jpg" alt="A grey cat sleeping on a windowsill" />
  • src: where the image file is, a relative path or a full URL.
  • alt: a text alternative for the image.

Writing good alt text

alt text is read aloud by screen readers and shown if the image fails to load. It’s also one of the signals search engines use to understand an image.

Describe what the image conveys, not just what it literally shows:

<!-- Weak: describes pixels, not meaning -->
<img src="chart.png" alt="chart" />

<!-- Better: describes what the image communicates -->
<img src="chart.png" alt="Bar chart showing sales doubling from Q1 to Q4 2025" />

If an image is purely decorative and adds no information, for example a background flourish, use an empty alt="". This tells screen readers to skip it entirely, rather than reading out the file name, which is far more disruptive than saying nothing.

<img src="divider-swirl.png" alt="" />

Never leave alt off entirely. A missing alt attribute is different from an empty one, screen readers may fall back to reading the file name, which is rarely useful.

Sizing images

Set width and height attributes (in pixels, as plain numbers) so the browser can reserve the right amount of space before the image loads. This prevents the page from jumping around as images load in, an issue known as layout shift.

<img src="cat.jpg" alt="A cat" width="600" height="400" />

You can still control the displayed size with CSS. The HTML attributes set the image’s intrinsic aspect ratio for layout purposes; CSS handles the actual responsive sizing:

img {
  max-width: 100%;
  height: auto;
}

Don’t use the old border attribute on <img> to add a border, it’s a presentational HTML attribute from before CSS handled styling. Use CSS instead:

<!-- Avoid -->
<img src="cat.jpg" alt="A cat" border="1" />

/* Better */
img {
  border: 1px solid #ccc;
}

Linking an image

Wrap an <img> in an <a> to make it clickable:

<a href="/gallery/cat-full-size.jpg">
  <img src="cat-thumb.jpg" alt="A grey cat sleeping on a windowsill" />
</a>

When an image is the only content of a link, the image’s alt text becomes the link’s accessible name, so it should describe where the link goes, not just what the picture shows.

Figure and figcaption

Use <figure> to group an image with its caption, and <figcaption> for the caption itself. This keeps the image and its caption tied together semantically, useful for photos, diagrams, and code snippets with captions.

<figure>
  <img src="cat.jpg" alt="A grey cat sleeping on a windowsill" />
  <figcaption>Our office cat, Biscuit, mid-afternoon nap.</figcaption>
</figure>

<figcaption> is optional, but when it’s present it must be the first or last child of <figure>.

Common mistakes

  • Leaving alt off entirely instead of using alt="" for decorative images.
  • Writing alt text that just repeats “image of” or “picture of”, screen readers already announce it as an image.
  • Skipping width/height, causing layout shift while images load.
  • Using an image of text instead of real text. Real text is selectable, searchable, and resizable; an image of text is none of those things.

FAQ

What if I don’t know the image dimensions yet?

Use CSS aspect-ratio alongside width/height attributes that match the image’s real proportions, or reserve space with a CSS container that has a fixed aspect ratio.

Should alt text include the file type, like “jpg image of a cat”?

No, that’s implementation detail no one needs. Describe the content and purpose of the image, not the file format.