useAltText (HTML)

Summary

Rule available since: v2.4.0
Diagnostic Category: lint/a11y/useAltText
This rule is recommended, meaning it is enabled by default.
This rule doesn’t have a fix.
The default severity of this rule is error.
Sources:
- Inspired from jsx-a11y/alt-text
- Same as @html-eslint/require-img-alt

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "a11y": {
5
        "useAltText": "error"
6
      }
7
    }
8
  }
9
}

Description

Enforce that all elements that require alternative text have meaningful information to relay back to the end user.

This is a critical component of accessibility for screen reader users in order for them to understand the content’s purpose on the page. By default, this rule checks for alternative text on the following elements: <img>, <area>, <input type="image">, and <object>.

Examples

Invalid

1
<img src="image.png" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <img src="image.png" />
      │ ^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content's purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.

1
<input type="image" src="image.png" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <input type="image" src="image.png" />
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content's purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.

1
<area href="foo" />

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the alt, aria-label, or aria-labelledby attribute.
  
  > 1 │ <area href="foo" />
      │ ^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content's purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.

1
<object data="foo"></object>

code-block.html:1:1 lint/a11y/useAltText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Provide a text alternative through the title, aria-label, or aria-labelledby attribute.
  
  > 1 │ <object data="foo"></object>
      │ ^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Meaningful alternative text on elements helps users relying on screen readers to understand content's purpose within a page.
  
  ℹ If the content is decorative, redundant, or obscured, consider hiding it from assistive technologies with the aria-hidden attribute.

Valid

1
<img src="image.png" alt="A beautiful landscape" />

1
<input type="image" src="image.png" alt="Submit" />

1
<img src="image.png" aria-label="A beautiful landscape" />

1
<img src="image.png" aria-labelledby="image-description" />

1
<object data="foo" title="Embedded content"></object>

1
<!-- Decorative images can be hidden from assistive technologies -->
2
<img src="decorative.png" alt="" />

1
<img src="decorative.png" aria-hidden="true" />

Accessibility guidelines

WCAG 1.1.1