Sections

Alt-text

Everything we know about alt-texts, when to use them, and how to craft them.

How to write alt-text

Section titled How to write alt-text

An alt-text is a description of an image that’s shown to people who can’t see the image. Alt-texts help people with little or no vision who use assistive technologies, people who have turned off images, and search engines.

Describe the image concisely

Section titled Describe the image concisely

It might sound obvious, but an alt-text should describe the image in case an image doesn’t display or someone has trouble seeing it. The goal of alt-text is to give the necessary information from the image at a glance. It’s best to include only the necessary information.

Man and woman using laptops at a standing table, Illustration.
Don’t Do
“People using computers.” “Man and woman using laptops at a standing table, Illustration.”
“Man in a purple shirt and woman in blue pants are typing on laptops and there’s a plant on the floor nearby.”
“Man and woman using computers, illustrated by Jane Doe © 2019.”

Take context into account. For instance, if the image above is part of a blog post about standing tables, then it’s safer to skip the part about standing tables.

Don’t say it’s an image

Section titled Don’t say it’s an image

Don’t start alt-texts with things like “Image of” or “Photo of.”. Screen readers add that by default. If it’s a special type of image (like an icon), you can note that at the end.

Don’t Do
“Image of a rocket.” “A rocket.”
“Illustration of a rocket.”
Photo of a rocket.”
“Icon of a rocket.” “A rocket, icon.”

End with a period

Section titled End with a period

End the alt-text with a period. This makes screen readers pause a bit after the last word in the alt-text, creating a natural pause before the next bit of text.

When not to write alt-text

Section titled When not to write alt-text

In most cases you should use an alt-text for images, but there are some exceptions where you should leave the alt-text blank.

Decorative images

Section titled Decorative images

If an image does not convey any meaning to the user, leave the alt-text blank. 

<div>
    <img src="rocket.svg" alt="">
    <h2>…</h2>
    <p>…</p>
</div>

Improve efficiency and ship better code

There’s a reason the world’s largest developer teams rely on Stack Overflow Enterprise—it leads to better product and allows distributed teams to securely collaborate and share knowledge.

The rocket here doesn’t add meaningful information.

Images accompanied by text

Section titled Images accompanied by text

If an image has a label nearby, leave the alt-text blank. 

<div>
    <img src="leaderboard.svg" alt="">
    <h2>…</h2>
    <p>…</p>
</div>

TOP LEADERBOARD: 728X90

This ad unit is the most visible on the site.

The nearby text here already explains what the graphic illustrates. If there was alt-text here, screen readers would repeat information to the user.

Note: In these cases, leaving the alt attribute empty (alt="") will cause a screenreader to skip over the image. Never remove the alt-attribute. When a screenreader comes to an image without an alt attribute, it will dictate the filename (Eg. “SO underscore logo dot png”).

How to add alt-text

Section titled How to add alt-text

Using <img>

Section titled Using <img>

Inside an <img> tag, add the alt-text inside the alt attribute: 

<img src="image.png" alt="The alt text.">
<img src="image.svg" alt="The alt text.">

Using inline SVG

Section titled Using inline SVG

Inline SVG doesn’t support the alt attribute, so instead add two wai-aria attributes: role="img" and aria-label="The alt-text.": 

<svg role="img" aria-label="the alt-text" viewBox="…">…</svg>

This content was adapted from Axess Lab.

Edit on GitHub