Everything I know about alt text

A good part of my job is telling peo­ple to use alt texts. To make my life eas­ier, here are all my notes and references in one place.

What is alt text?

"Alt text" is short for "alternative text". It's a short piece of text that's used when the image itself isn't available because someone is using a text-only or audio version of your website, they turned off images to save bandwidth, or the network request failed. Alt text also makes your images more readable for machines, both your own and those built by others.

It's different to an image caption, which provides additional context to an image and is visible to everyone, or an extended description.

Why should you use alt text?

Alt text is a straightforward way to give more people access to your content. This includes people who are blind or have low vision and rely on screen readers and other assistive technology, but also people who are cooking, driving, on a slow internet connection, or in some other situation where an audio or text-only version of your website is just more convenient.

If your organisation takes public money, you're probably required to provide alt text by your country's accessibility laws. In the U.S. the relevant standard is Section 508 of the Rehabilitation Act and the Americans with Disabilities Act (ADA)1, in Britain it's the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018, and European member states all have local laws implementing a directive called EU 2016/2102. Thankfully, all of these laws refer to a common standard called the Web Content Accessibility Guidelines (WCAG), which requires that "all non-text content is also available in text" (Success Criterion 1.1)

How do you write good alt text?


Alt text should give people the same information as the image it replaces. This means you need to ask what the purpose of the image is in the context it's in and write different alt text depending on the answer.

Let's say your website has a phone number with an icon of a phone next to it. The purpose of that icon is just to indicate that what follows is, in fact, a phone number – so the alt text should do the same. The word "Phone" would be enough to do that. Any other details would be distracting.

If the point of an image is to show what something looks like, the alt text should be a visual description of that thing, focusing on the important details. If the image is a photo of a boat you're trying to sell, you should focus on the boat rather than the landscape in the background. However, if you used the same image as an example of your landscape photography, describing the background, the light, and the overall composition would make sense.

People have come up with more formal categories of images and rules for writing alt texts for each. These can be useful, but ultimately these are editorial decisions you need to make using your own judgement.


I think it's helpful to remind yourself that writing alt text is still writing. It's not fundamentally different from any other writing you do on your website. This means you can use everything you know about your audience, structure, tone, editing and so on, and be as nuanced and expressive as you are in other contexts. If you think of it as a literary endeavour rather than a technical chore, writing alt text can be fun and you'll likely produce better results.

This being said, some basic style tips are generally accepted:

How do you add alt text?

It depends on your situation. If you're working with HTML, you write the alt text right into your markup using the alt attribute:

<img alt="Charcoal drawing of apples on checked blanket" src="apples.jpg" />

Inline SVGs don't support the alt-attribute, but you can use role="img" and aria-label instead:

<svg role="img" aria-label="Diagram of an internal combustion engine" viewBox=""></svg>

If you're not editing your site's HTML directly, you need to figure out how to add alt text through your content management system. Most popular ones have built-in tools to do it:

If your CMS doesn't support alt text, you can work around the problem by adding captions or describing the image in the main text.

Can you automate this?

Some people do generate alt text automatically when no hand-written text is available, notably Facebook and its properties and Microsoft Edge.

The problem with these systems is that they have no way of knowing what you were trying to communicate with a particular image. They just produce a general, more or less accurate description of it, which isn't always what your readers need (see above). Still, in most situations it's probably better than no description at all.

Further reading

  1. The U.S Department of Justice has some re­ally well-writ­ten guid­ance on how the ADA re­lates to web ac­ces­si­bilty. ↩︎