View source for Using aria-labelledby to provide a text alternative for non-text content

[[Category: Techniques]]
[[Category: ARIA Techniques]]
[[Category: Techniques Accepted]]
[[Category: Ready for XML]]

== Status ==

* 1 Nov 2012: TF FtF says this technique needs additional work.
* 1 Nov 2012: Ready for TF review
* [https://www.w3.org/2002/09/wbs/35422/20130110aria/ Surveyed by WG 10 Jan 2013]
* Reviewed by TF in [https://www.w3.org/2002/09/wbs/35422/20130808ttf/results#xlabelled Techniques Task Force: ARIA techniques for 8 Aug 2013]
* approved by WG Sept 10, 2013 (http://www.w3.org/2013/09/10-wai-wcag-minutes.html)
* added to XML by AWK 2014/1/2

=== User Agent Notes [To be published separately] ===

* Jaws 13+ support Example 1 with IE and FF
* NVDA 2012.3 supports both Example 1 and Example 2 with FF

== Applicability ==

This technique applies to HTML with WAI-ARIA.


This technique relates to:
* [http://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html Success Criterion 1.1.1 (Text Alternatives)]
** [http://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html Understanding SC 1.1.1]
** [http://www.w3.org/WAI/WCAG20/quickref/#qr-text-equiv-all How to meet SC 1.1.1]

== Description ==

The purpose of this technique is to provide a short description for an element that can be read by assistive technologies (AT) by using the <code>aria-labelledby</code> attribute. The <code>aria-labelledby</code> attribute associates an element with text that is visible elsewhere on the page by using an ID reference value that matches the ID attribute of the labeling element. Assistive technology such as screen readers use the text of the element identified by the value of the <code>aria-labelledby</code> attribute as the text alternative for the element with the attribute.

Note: When using <code>aria-labelledby</code> attribute on an <code>img</code> element, the absence of an <code>alt</code> attribute will cause validation failures for HTML 4 and earlier and XHTML. If <code>alt</code> is provided, it must contain the same text as the <code>aria-labelledby</code> target. Do not use <code>alt=""</code>, which would cause some assistive techology to ignore the image completely.

== Examples ==

=== Example 1 ===

This example shows how to use the <code>aria-labelledby</code> attribute to provide a short text description for an image, using a piece of text that is visible on the page.

<pre>
<img src="sunflowers.jpg" aria-labelledby="flower_id">

...

<span id="flower_id">Van Gogh's oil painting of sunflowers</span>
hangs in Amsterdam's Van Gogh museum.
</pre>

=== Example 2 ===

This example shows how to use the <code>aria-labelledby</code> attribute to provide a short text description for a read-only complex graphic of an star rating pattern; the graphic is composed of several image elements. The text alternative for the graphic is the label, visible on the page beneath the star pattern.

<pre>
<div role="img" aria-labelledby="star_id">
<img src="fullstar.png" alt=""/>
<img src="fullstar.png" alt=""/>
<img src="fullstar.png" alt=""/>
<img src="fullstar.png" alt=""/>
<img src="emptystar.png" alt=""/>
</div>

<div id="star_id">4 of 5</div>
</pre>

== Resources ==

* [http://www.w3.org/TR/wai-aria-practices/ WAI-ARIA 1.0 Authoring Practices]
* [http://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation]

== Related Techniques ==

* [http://www.w3.org/TR/WCAG-TECHS/H37.html H37: Using alt attributes on img elements]

== Tests ==

=== Procedure ===

# Examine each element where the <code>aria-labelledby</code> attribute is present.
# Check whether the value of the <code>aria-labelledby</code> attribute is the id of an element on the web page
# Determine that the text of the element identified by the <code>aria-labelledby</code> attribute accurately labels the element, provides a description of its purpose, or provides equivalent information.

=== Expected results ===

* Checks #2 and #3 are true.