WCAG H37: Require images to have alternative text

Rule ID:

wcag/h37

Category:

Accessibility

Standards:

• 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:

<img>

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="...">

Options

This rule takes an optional object:

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

allowEmpty

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>

alias

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="...">