Alt text
Everything we know about alt-texts, when to use them, and how to craft them.
How to write alt-text
For a helpful decision tree on how and when to write alt-text, check out the W3C’s alt-text decision tree, or the advice from Meta which helped inform this guide.
An alt-text is text that describes an image, or that should otherwise be displayed in place of an element that can’t be rendered for any reason. Alt-texts help blind and low-vision people who use assistive technologies, people who have turned off images, and search engines. Good alt-text is an important element of accessibility: it lets blind and low-vision users experience and value our content as much as sighted users can.
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, while ensuring you convey the same thing the image is meant to convey.
Your alt-text can be more succinct if the body text around the image already explains or references its contents — you can convey the same meaning contextually to users who can’t see it.
Don’t
- "People using computers."
- "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."
Do
- "Man and woman using laptops at a standing table, Illustration."
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
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
- "Image of a rocket."
- "Illustration of a rocket."
- "Photo of a rocket."
- "Icon of a rocket."
Do
- "A rocket."
- "A rocket, icon." (if noting the type)
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
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
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>The rocket here doesn’t add meaningful information.
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>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
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
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.