== Why is this an issue?

The ``++alt++``, ``++aria-label++`` and ``++aria-labelledby++`` attributes provide a textual alternative to an image.

It is used whenever the actual image cannot be rendered.

Common reasons for that include:

* The image can no longer be found
* Visually impaired users using a screen reader software
* Image loading is disabled, to reduce data consumption on mobile phones

It is also very important not to set an alternative text attribute to a non-informative value. For example, ``++<img ... alt="logo">++`` is useless as it doesn't give any information to the user. In this case, as for any other decorative image, it is better to use a CSS background image instead of an ``++<img>++`` tag. If using CSS ``++background-image++`` is not possible, an empty ``++alt=""++`` is tolerated. See Exceptions below.


This rule raises an issue when:

* An ``++<img>++`` element has no ``++alt++`` attribute.
* An ``++<input type="image">++`` element has no ``++alt++``, ``++aria-label++`` or ``++aria-labelledby++`` attribute or they hold an empty string.
* An ``++<area>++`` element within an image map has no ``++alt++``, ``++aria-label++`` or ``++aria-labelledby++`` attribute.
* An ``++<object>++`` element has no inner text, ``++title++``, ``++aria-label++`` or ``++aria-labelledby++`` attribute.

=== Exceptions

``++<img>++`` elements with an empty string ``++alt=""++`` attribute won't raise any issue. However, this way should be used in two cases only:


When the image is decorative and it is not possible to use a CSS background image. For example, when the decorative ``++<img>++`` is generated via javascript with a source image coming from a database, it is better to use an ``++<img alt="">++`` tag rather than generate CSS code.

[source,html]
----
<li *ngFor="let image of images">
    <img [src]="image" alt="">
</li>
----
When the image is not decorative but its ``++alt++`` text would repeat a nearby text. For example, images contained in links should not duplicate the link's text in their ``++alt++`` attribute, as it would make the screen reader repeat the text twice.

[source,html]
----
<a href="flowers.html">
    <img src="tulip.gif" alt="" />
    A blooming tulip
</a>
----
In all other cases you should use CSS background images.

== How to fix it

Add an alternative text to the HTML element.

=== Code examples

==== Noncompliant code example

[source,html,diff-id=1,diff-type=noncompliant]
----
<img src="foo.png" /> <!-- missing `alt` attribute -->
<input type="image" src="bar.png" /> <!-- missing alternative text attribute -->
<input type="image" src="bar.png" alt="" /> <!-- empty alternative text attribute on <input> -->

<img src="house.gif" usemap="#map1"
    alt="rooms of the house." />
<map id="map1" name="map1">
  <area shape="rect" coords="0,0,42,42"
    href="bedroom.html"/> <!-- missing alternative text attribute on <area> -->
  <area shape="rect" coords="0,0,21,21"
    href="lounge.html" alt=""/> <!-- empty `alt` attribute on <area> -->
</map>

<object {...props} />  <!-- missing alternative text attribute on <area> -->
----

==== Compliant solution

[source,html,diff-id=1,diff-type=compliant]
----
<img src="foo.png" alt="Some textual description of foo.png" />
<input type="image" src="bar.png" aria-labelledby="Textual description of bar.png" />

<img src="house.gif" usemap="#map1"
    alt="rooms of the house." />
<map id="map1" name="map1">
  <area shape="rect" coords="0,0,42,42"
    href="bedroom.html" alt="Bedroom" />
  <area shape="rect" coords="0,0,21,21"
    href="lounge.html" aria-label="Lounge"/>
</map>

<object>My welcoming Bar</object>
----

== Resources
=== Documentation

* W3C - https://www.w3.org/WAI/tutorials/images/decision-tree/[W3C WAI Web Accessibility Tutorials]
* W3C - https://www.w3.org/TR/WCAG20-TECHS/H24.html[Providing text alternatives for the area elements of image maps]
* W3C - https://www.w3.org/TR/WCAG20-TECHS/H36.html[Using alt attributes on images used as submit buttons]
* W3C - https://www.w3.org/TR/WCAG20-TECHS/H37.html[Using alt attributes on img elements]
* W3C - https://www.w3.org/TR/WCAG20-TECHS/H67.html[Using null alt text and no title attribute on img elements for images that AT should ignore]
* W3C - https://www.w3.org/TR/WCAG20-TECHS/H2.html[Combining adjacent image and text links for the same resource]
* W3C - https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-text-equiv-all[Non-text Content]
* W3C - https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-navigation-mechanisms-refs[Link Purpose (In Context)]
* W3C - https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-navigation-mechanisms-link[Link Purpose (Link Only)]
