Does the <img> have the correct alt text?


Ensure that we are providing text alternatives for people who can’t see the icon or image in the <img> element.

Why this matters

  • Assistive technology provides the alternative text to people using screen readers or Braille displays. If you don’t provide alternative text, it reads the file name.
  • Browsers provide the alt text to all users if the image doesn’t load. Alt text ensures that a broken or missing image file doesn’t break the usability of the page.

How to implement

  • See SVG titles and image alt text for writing the words themselves.
  • If adding the html manually the code should be <img src=”...” alt=”...”> where the ellipses stand in for the relevant values.
  • See MDN’s article <map> for implementing an image map.

The alt text of an image is calculated in the following order of precedence by screen readers:

  1. aria-labelledby
  2. aria-label
  3. The alt attribute. (Note the alt text won’t be read at all if either of an aria-labelledby or aria-label attribute is present.) 
  4. The title attribute as a last resort. (This is unreliable.)

How to test

Manual testing

  1. Right-click and inspect the element in the browser’s developer tools. Ensure that the image has an alt attribute and that it’s set to a value.
  2. Assuming it does have a value, ensure that the title matches your Writer’s expectations.

Automated testing

  • HTML validators should identify <img> elements without valid alt attributes.
  • Note that you still have to do manual testing to ensure it’s the correct wording in the alt attribute! Automated testing won’t warn you that you labeled a hockey stick with the alt text “cheese”.