text-image-alt-text
Included in config: ✅ recommended, 🔒 strict
Alternative text, or “alt text”, is a description attached to an image. It allows non-sighted users and tools to understand the image despite not being able to visually see it.
Setting Alt Text
Section titled “Setting Alt Text”Images should have alt text that describes their contents as if the reader cannot see the image at all. In other words, a reader should be able to understand the meaning of the image without looking at it.
Blank or “file name” alt text content is not enough:
- ❌
: does not indicate what the image is at all - ❌
: reads as “base-octocat.svg”, which does not explain what the image is
Image alt text should briefly explain what’s in the image so that a non-visual reader doesn’t miss any information:
- ✅
“When Is Alt Text Necessary In Open Source?”
Section titled ““When Is Alt Text Necessary In Open Source?””Always.
For web pages in general, alt text is necessary when an image is not “decorative” (such as a background image with no real content).
Decorative images may be marked as decorative or hidden, such as by using alt="".
Inline images in GitHub comments are never decorative. They are also always set as links to the image file.
You should always put proper alt text on images. Not doing so restricts users who can’t visually see it:
- People who have low or no sight, including people who are “blind”, and rely on screenreaders to narrate page contents
- People who are on slow network connections that take too long to -or cannot at all- download images
Examples
Section titled “Examples”Issue with an image lacking alt text:
See More
Section titled “See More”- github/accessibility-alt-text-bot: a GitHub Action dedicated to image alt text detection
- GitHub Docs: Basic writing and formatting syntax > Images
- Rule source
- Rule tests
[text-image-alt-text]
The following image is missing alt text:
Alternative text, or “alt text”, is a description attached to an image. It allows non-sighted users and tools to understand the image despite not being able to visually see it. To resolve this report, add descriptive alt text to the image.