All rules

Sheath rule

a11y-alt-text

Images must have an alt attribute for accessibility.
Package
Core
Category
Accessibility
Default severity
error by default
Auto-fix
Manual fix

#Why

Screen readers use alt text to describe images to people who are blind or have low vision. Without alt text, those readers may miss the image's meaning. The alt attribute is required by WCAG 2.2 Success Criterion 1.1.1 (Non-text Content).

#Examples

#Bad

<!-- Missing alt attribute -->

<img src="logo.png">



<!-- Missing alt on image with other attributes -->

<img src="hero.jpg" class="banner" width="800">

#Good

<!-- Descriptive alt text -->

<img src="logo.png" alt="Company Logo">



<!-- Alt text describing the image purpose -->

<img src="hero.jpg" alt="Welcome banner showing our team" class="banner">



<!-- Empty alt for decorative images -->

<img src="decorative-border.png" alt="">



<!-- An explicit image role needs a non-empty accessible name -->

<img src="chart.png" alt="" role="img" aria-label="Quarterly sales chart">

#Options

Use this option to decide whether an empty alt value is acceptable.

Option Type Default Description
requireNonEmpty boolean false When true, empty alt attributes are also flagged 
<?php



'a11y-alt-text' => ['error', ['requireNonEmpty' => true]],

#Notes

  • Use descriptive alt text that conveys the image's purpose
  • For decorative images, use an empty alt="" attribute (not missing)
  • Do not combine an empty alt with an explicit img/image role unless another naming attribute provides a non-empty accessible name
  • Any global ARIA property conflicts with empty-alt presentation semantics and restores the native image role. aria-label or a resolved aria-labelledby can then name the image; aria-describedby and title cannot override a present-but-empty alt
  • Don't include "image of" or "picture of" in alt text - screen readers already announce it as an image
  • Keep alt text concise but meaningful
  • Opaque attribute spreads such as {{ $attributes }} make the final alt value unknowable and are not checked. If any explicit Blade branch can emit the image without alt, the image is reported

#References

#Related Rules