View source for Using aria-label to provide labels for objects


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

== Status ==
===Status===
[https://www.w3.org/2002/09/wbs/35422/htmltechs20121005/results surveyed by TF ]
* 1 Nov 2012: Ready for WG Review
* Added to XML by AWK 2014/1/2

=== User Agent Notes [To be published separately] ===
*Jaws V.11 and greater has complete support.
*ChromeVox V.1 and greater has complete support 
*VoiceOver V.3 and greater supports ???
*NVDA 2 supports Aria Describedby ???
*Window Eyes as of V.7 ???.

=== Applicability ===
As of this writing this technique applies to HTML technologies. 

This technique relates to:

* [http://www.w3.org/TR/UNDERSTANDING-WCAG20/text-equiv-all.html Success Criterion 1.1.1 (Text Alternatives)

===Description===

The purpose of this technique is to provide a label for objects that can be read by assistive technology. The <code>aria-label</code> attribute provides the text label for an object, such as a button. When a screen reader encounters the object, the <code>aria-label</code> text is read so that the user will know what it is.

Authors should be aware that aria-label may be disregarded by assistive technologies in situations where aria-labelledby is used for the same object. For more information on the naming hierarchy please consult the [http://www.w3.org/TR/wai-aria/roles#textalternativecomputation ARIA specification] and the [http://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation accessible name and description calculation] in the HTML to Platform Accessibility APIs Implementation Guide. Authors should be aware that use of <code>aria-label</code> will override any native naming such as <code>alt</code> on images or <code>label</code> associated with a form field using the <code>for</code> attribute.

===Examples===
====Example 1====
The following example shows how a <code>aria-label</code> could be used to distinguish two navigation landmarks in a HTML4 and XHTML 1.0 document, where there are more than two of the same type of landmark on the same page, and there is no existing text on the page that can be referenced as the label. 

<pre>
<div role="navigation" aria-label="Primary">
<ul><li>...a list of links here ...</li></ul> </div>
<div role="navigation" aria-label="Secondary">
<ul><li>...a list of links here ...</li> </ul></div>
</pre>

====Example 2====
The following example shows how a generic "region" landmark might be added to a weather portlet. There is no existing text on the page that can be referenced as the label, so it is labelled with aria-label. 

<pre>
<div role="region" aria-label="weather portlet"> 
...
</div>
</pre>

====Example 3====
Below is an example of a math ML function, using the math role, appropriate label, and MathML rendering:

<pre>

<div role="math" aria-label="6 divided by 4 equals 1.5">
  <math xmlns="http://www.w3.org/1998/Math/MathML">
    <mfrac>
      <mn>6</mn>
      <mn>4</mn>
    </mfrac>
    <mo>=</mo>
    <mn>1.5</mn>
  </math>
</div></pre>

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

===Related Techniques===
*[http://www.w3.org/TR/WCAG20-TECHS/xxxxx.html ARIA-XX: Using aria-labelledby to provide labels for objects.]
*[http://www.w3.org/TR/WCAG20-TECHS/H44.html H44: Using label elements to associate text labels with form controls]

===Tests===
====Procedure====
For each element where a <code>aria-label</code> role attribute is present.
#Examine whether the text description accurately labels the object or provides a description of its purpose or provides equivalent information.

====Expected Results====
Test #1 is true.