In this week’s Best Practice of the Week, we’re talking about how to provide descriptive alt attributes for images.

Any image on your website which shows useful information must have an alt attribute which describes the image. Without an alt attribute, users who can’t see your images are treated to the filename or file path of the image instead. At best, your non-sighted users will find this boring. But at worst it’s confusing and hides vital information from people who need it.

Alt attributes are so important for non-sighted users that it’s worth taking the time to learn how to write them properly, by using the correct markup and making sure they are useful.

The easy part: alt attribute markup

Adding an alt attribute to an image is as simple as adding its width or height attributes—you just put it inside the image tag as shown below:

<img alt="Logo" src="logo_sa.jpg" width="200px" height="300px">

The difficult part: useful content

Although the example above is valid HTML, it’s not very useful to anyone who needs a text alternative. Users who can’t see it will be left wondering whose logo it is and what it’s doing there.

Even with a very basic graphic, there are a lot of details which could be included: its text, colours, objects in the foreground or background, orientation to portrait or landscape, etc. The important thing is to keep your users’ needs in mind, the same as you would for any other aspect of your site. Ask yourself the following questions when you are writing your alternative content:

What is the purpose of this image?

There’s an old saying that a picture can speak a thousand words. But browsers and screenreaders vary in the amount of alternative content they will present to your user, so you need to keep it short and sweet. Which of those thousand words are important to your content?

Think about why you chose that image and what you would want people to know about it if they couldn’t see it. Use the alt attribute to specifically describe the important parts of the image, and leave out details like whether it’s portrait or landscape oriented, or clipart, or has 27 trees in the background.

Some images don’t have useful information. Maybe they were included to make your site more pleasant to look at, or to provide emphasis to parts of the interface. In that case you’ll need to take a different approach, and we’ll cover that in another Best Practices post soon.

What is the context of the image?

The same image might convey different information depending on where it’s placed. For example, the logo in my example above might be used as a link to the home page of the company website, as an example of a font, or on a list of sponsors for an event.

The Simply Accessible logo.

Any of these might be useful alt attributes in different situations:

“Simply Accessible”
“An example of the font Today SH-Medium used in a company logo.”

You also need to take into account if information in the image has already been written in the content around it. You don’t need to repeat details which are in the image caption, or mentioned in a part of the page discussing the image.

For example, if our logo was in a group of other logos with the heading “Sponsors” above it, the context makes it clear that Simply Accessible is one of those sponsors so there is no need to mention it in the alt attribute.

If your image is a link to other content, you’ll need to take that into account. We’ll be talking about that in another Best Practices post soon.

Is this too much information to fit in an alt attribute?

If you have a complicated or very detailed image which can’t be described succinctly, an alt attribute is not going to be enough to help your non-sighted users.

A full description in the main content might be useful to everyone, and it’ll give you the opportunity to draw attention to specific details of the image. Another option is to include a link near the image which goes to a page with a full description.

The alt attribute can then be used to indicate there is a more comprehensive description elsewhere so that non-sighted users know where to find it.

<img alt="Graph of rainfall rates in Western Australia between 1901 and 2000, as described above." src="rainfall_wa.gif" width="500" height="400">

Further suggestions


  • Include introductory phrases like “An image of…” or “Graphic:…”. Sighted users who have turned images off will see the broken image icon, and screenreader software announces “Graphic” before reading the alt attribute. For the same reason, images which are links don’t need to have that mentioned in their alt content either.
  • Include HTML elements. Putting elements inside the attribute of another element is invalid markup. Screenreader software will usually ignore it, but sometimes misinterpret it.


  • Put the most important information first in the attribute.
  • Include a full-stop at the end of the text. This is a nice touch since it makes screenreader software pause briefly after reading it instead of rushing on to the next element, the same way it does for sentences in a paragraph.
  • Remember that although an automated accessibility checker can see if all the images have alt attributes, you are the best judge of how useful the content in those attributes is to your audience.

One thought on “Writing descriptive alt attributes for images”

Read comments

Hi there! We've closed the comments after a week of spirited discussion on this post. If there's something we've missed, please reach out and let us know.