WCAG H37: Require images to have alternative text

Rule ID:
  • WCAG 2.2 (A)
  • WCAG 2.1 (A)
  • WCAG 2.0 (A)

Both HTML5 and WCAG requires all images to have an alternative text. Assistive technology such as screenreaders relies on the alt-text to provide a description of the image.

Purely Decorative images must use empty (null) alt="" attribute (preferred) or be excluded from accessibility tree with role="presentation" or aria-hidden="true".

See wcag/h36 for a similar rule for <input type="image">.

Rule details

Examples of incorrect code for this rule:

error: <img> is missing required "alt" attribute (wcag/h37) at inline:1:2:
> 1 | <img>
    |  ^^^

1 error found.

Examples of correct code for this rule:

<img alt="...">


This rule takes an optional object:

  "allowEmpty": true,
  "alias": []


Sometimes images are used in context where the image only adds to the user experience but is already clear from an A11Y perspective.

When true this allows empty <img alt=""> to be used to prevent errors and to signal that the image is not meant to be read.

Examples of correct code with this option enabled:

<span>The task was successfully completed! <img src="thumbsup.png" alt=""></span>


If javascript is used to set the attribute on-the-fly (e.g. using angular-translate) the alternative attributes can be listed here.

Examples of correct code when alias is ["data-alt"]:

<img data-alt="...">