Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Alt text for images

It is common knowledge that images are required to have an alt attribute. This is one of the primary rules of accessibility for web pages (defined in WCAG 2.1 Principle 1, Success Criterion 1.1.1). Nevertheless, coming up with a good alt text for an img element might be easier said than done. Here are some guidelines that may help you:

  1. The alt text is meant to be a description of the image, not a title, hint, or tooltip. Try to describe the image with a clear and concise sentence. What do you see when you look at the image? Is it a "Purple dinosaur with a Santa hat on its head", or a "Red exclamation mark emitting yellow sparks"? A good textual description of an image makes it possible for blind and sighted users to talk about an element, which is especially important if it's a significant element. For example, imagine if a link to a contact information page is just an envelope icon with the alt text "Contact us". That could easily create confusion if e.g. a blind user trying to help their sighted grandma by telling her to click on the "Contact us" link, and she feels even more stupid because she can't see such a link anywhere on the page.
  2. Do not start the text by stating that it is "Image of", since this is already implied by the semantics of the img element. It's like saying, "Image of image..."
  3. Do not use the same text that is also displayed in an adjacent element such as a heading. Those who see the alt text instead of the graphics don't want the exact same text twice.
  4. If it's technically impossible to provide a good description for an image whose presence is significant, then you may resort to a more generic alt text, such as "User's main profile picture", or "Uploaded image 1" (or use date and time instead of index).
  5. Never omit the alt attribute. However, if the image is insignificant and merely for decorative purposes, then you may use an empty string as alt text as a last resort. An empty alt indicates to assistive technology that the presence of the image should be ignored.

P.S.: Give SVG elements alt text too! Either by creating a title element as the first child element of the svg, or by setting role="img" and aria-label="The alt text" on the svg element. The latter won't generate any tooltips on mouse-over events!


This comment has been minimized.

Copy link

@digitalsadhu digitalsadhu commented Mar 1, 2019

This is excellent, hard to find fault. It reads very well and most of the 4 suggestions I give below could easily be ignored.

Intro section

  • I would change "might be easier said than done" to "is easier said than done". This is not a major, just feels slightly better to me. Feel free to ignore.

Section 1.

Of the 4 suggestions I've made, this one is probably the most important I think. There was something a bit awkward with the second half of this paragraph and I've taken some artistic license and attempted a bit of a rework (risking of course that I perhaps inject a bit too much of my own personality into your writing).

  • As an example, imagine a link to a contact information page which is just an envelope icon with the alt text "Contact us". This could easily create confusion. Imagine now a blind user trying to help their sighted grandma by telling her to click on the "Contact us" link. Visually, there is no such link and now the poor grandmother feels even more stupid for not being able to see the link.

Section 2.

Both the suggestions here can be safely ignored. Both are just what I consider slightly more correct wordings. (Based on hunches/feelings)

  • Consider changing "by stating that it is" to just "with"
  • Consider changing "It's like saying" to "This would be like saying"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment