Skip to main content Accessibility Feedback

How to write good alt text

The alt attribute is used with img elements to provide descriptive text that can be read aloud by screen readers and other assistive technology.

Today, I wanted to talk about what good alt text looks like, and some common mistakes I see people make. Let’s dig in!

Example alt text

For example, here’s a photo of a crab.

<img src="/imgs/edgar-the-crab.jpg">

By default, a screen reader would announce, “/imgs/edgar-the-crab.jpg” for this image.

If we add an alt attribute with a description of the image, that will be read aloud instead.

<img
	alt="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
	src="/imgs/edgar-the-crab.jpg"
>

Now, a screen reader would announce, “A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him.” This allows visually impaired users to get the same information from the image that someone who doesn’t need assistive technology would.

Writing good alt text

When writing alt text, try to describe the details of the image rather than simply stating what it is.

Using the photo of Edgar the crab as an example, “The crab I met on my vacation” would be bad alt text. While it’s descriptive, it doesn’t actually describe the content of the image itself.

<!-- This is bad alt text -->
<img
	alt="The crab I met on my vacation"
	src="/imgs/edgar-the-crab.jpg"
>

What about the title attribute?

The title attribute is also often read aloud by screen readers, and many people incorrectly assume that you can use title and alt interchangeably.

<!-- Do not use the title attribute to provide alt text -->
<img
	title="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
	src="/imgs/edgar-the-crab.jpg"
>

Similarly, do not use the same text for both the title and alt attributes, as it will be read aloud twice by many screen readers.

<!-- A better use of the title attribute -->
<img
	alt="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
	title="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
	src="/imgs/edgar-the-crab.jpg"
>

The title attribute is supposed to provide the kind of information you might find in a caption. For example, “The crab I met on my vacation” would be more appropriate for a title.

<!-- A better use of the title attribute -->
<img
	title="The crab I met on my vacation"
	alt="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
	src="/imgs/edgar-the-crab.jpg"
>

That said, in most situations, wrapping an image in a figure element, adding that text as a figcaption, and not including a title attribute is typically a better option, since its both exposed visually and read aloud by screen readers.

<!-- This is generally better than using the title attribute -->
<figure>
	<img
		alt="A crab standing in wet, packed sand, waving as the tide gently laps the shore behind him"
		src="/imgs/edgar-the-crab.jpg"
	>
	<figcaption>The crab I met on my vacation</figcaption>
</figure>

Decorative images

Every now and then you might have an image that’s purely decorative in nature.

Aside: images are “just decorative” far less often than you might think.

When that’s the case, it’s better to use an empty string for your alt text rather than omit the attribute entirely.

<!-- Use only for decorative images -->
<img alt="" src="/imgs/my-decorative-image.jpg">

Without the attribute, screen readers will read the filename of the image. With an empty string, it won’t announce anything, which is more appropriate for an image that’s purely decorative.