View source for Using aria-label to provide an invisible label

[[Category: Techniques]]
[[Category: ARIA Techniques]]
[[Category: Techniques In Development]]

== Status ==

* [https://www.w3.org/2002/09/wbs/35422/htmltfJun182012/results#xlabel1 Surveyed by TF 25 June 2012]
* [http://www.w3.org/2012/06/25-html-techs-tf-minutes Discussed by TF 25 June 2012]

=== Editorial note===
The title of this technique might be changed to "Using aria-label to provide an invisible label when there is no visible label but the context and visual appearance of the control make its purpose clear" (Loretta) or "Using aria-label to provide a programmatically determinable label" (Adam)

== User Agent Notes [To be published separately] ==
Screen reader support varies depending on browser:
* System Access To Go (IE8) does not recognise <code>aria-label</code>
* Using NVDA with Firefox (FF), <code>aria-label</code> is only spoken on custom controls
* Using NVDA with Internet Explorer (IE), <code>aria-label</code> is only spoken on native controls
* JAWS has the best support of <code>aria-label</code> 

Here are the results of some detailed testing: 

*JAWS 13 (WIN7, FF13)
**Example 1: JAWS speaks <code>aria-label</code> of <code>div</code> set to <code>contentEditable</code> but not the content of the div (the word to be corrected)
**Example 2: JAWS speaks <code>aria-label</code>: "close button"
**Example 3: JAWS does not speak the <code>aria-label</code>, just says "button"

*JAWS 13 (WIN7, IE9)
**Example 1: JAWS speaks <code>aria-label</code>, but the content of <code>div</code> boxes is only spoken in Virtual PC cursor mode, not when tabbing to the <code>div</code>s
**Example 2: JAWS speaks content of <code>div</code> box (focus is being moved to its beginning through the skip link) followed by <code>aria-label</code>: "close button"
**Example 3: JAWS speaks the <code>aria-label</code>

*NVDA 2011.3 (XP, FF13) 
**Example 1: NVDA speaks specified <code>aria-label</code> of <code>div</code> set to <code>contentEditable</code>, followed by announcing "section editable" and, for mis-spelled words, "spelling error"
**Example 2: NVDA does not speak the <code>aria-label</code>, just "X button"
**Example 3: NVDA does not speak the <code>aria-label</code>, just "button" (- and + are dropped, but this may be customizable in screen reader settings)

*NVDA 2011.3 (XP, IE8) 
**Example 1: Browser focuses <code>div contentEditable</code> but apparently does not expose them to the accessibility API so NVDA does not speak associated contents of <code>aria-label</code>
**Example 2: NVDA speaks the <code>aria-label</code> content, "button close", instead of the text included in the button (X)
**Example 3: NVDA speaks the <code>aria-label</code> content

*NVDA 2012.2.1 (WIN7, IE9)
**Example 1: Same as under (XP, IE8): <code>div contentEditable</code> received focus but <code>aria-label</code> is not exposed to accessibilty API
**Example 2: NVDA speaks <code>aria-label</code> "This is a div box button close" in browse mode and "close button" in focus mode
**Example 3: Content of <code>aria-label</code> spoken

*NVDA 2012.2.1 (WIN7, FF13)
**Example 1: NVDA speaks specified <code>aria-label</code> for custom div set to contentEditable, followed by announcing "section editable" (but no announcement of mis-spelled words here)
**Example:2 Does not speak <code>aria-label</code> of X-button
**Example 3: NVDA does not speak <code>aria-label</code> for + and - button (- and + are dropped, but this may be customizable in screen reader settings)

* System Access To Go (XP, IE8): In all three examples, SAToGo does not recognise <code>aria-label</code>
**Example 1: SAToGo speaks "editable text" followed by the text in <code>div contentEditable</code>
**Example 2: After activating Link, SAToGo speaks content of the pop-up <code>div</code> followed by "button X
**Example 3: By default, SAToGo speaks "plus button" and "hyphen button" - not the content of <code>aria-label</code>

=== Applicability ===
This technique applies to technologies that support WAI-ARIA, such as HTML. 

This technique relates to:

* [http://www.w3.org/TR/WCAG/#minimize-error-cues Success Criterion 3.3.2 Labels or Instructions]

===Description===
In some contexts, elements can be given the attribute <code>aria-label</code> to provide an accessible name for situations when there is no visible label due to a chosen design approach or layout but the context and visual appearance of the control make its purpose clear.

For sighted users, the context and visual appearance of an element can provide sufficient cues to determine their purpose. An example is the 'X' often used in the top right corner of pop-up divs (light boxes) to indicate the control for closing the div.  

In other contexts, the use of native HTML elements such as <code>label for</code> is not possible - for example, when a <code>div</code> set to <code>contentEditable</code> is used instead of native form elements such as <code>input type="text"</code> or <code>textarea</code> in order to provide a richer text editing experience.

===Examples===
====Example 1: A quiz using divs set to contentEditable====
''Note:'' The accessibility support of <code>aria-label</code> on <code>div</code>s with the attribute <code>contentEditable="true"</code> is currently still weak.

On a page, a spelling quiz uses <code>div</code>s with the attribute <code>contentEditable="true"</code>.

Since the text input elements used in the quiz are not form elements, label cannot be used. Instead, <code>aria-label</code> is used to provide short labels ("Correct first word", "Correct second word", etc.) to the editable divs.



<pre>
<div class="quizbox">
  <h3>The spelling quiz</h3>
  <p id="instruction">Correct the spelling of the four words below. When you are done, press submit!</p>
  <div aria-label="Correct first word" contenteditable="true">ancilary</div>
  <div aria-label="Correct second word" contenteditable="true">parsemonious</div>
  <div aria-label="Correct third word" contenteditable="true">serendipidous</div>
  <div aria-label="Correct fourth and last word" contenteditable="true">voiciferous</div>
  <button type="submit">Submit</button>
</div>
</pre>

Look at [http://www.3needs.org/en/testing/code/aria-label-1.html  Example spelling quiz, with test results]

====Example 2: A close button (X) in a pop-up div====
On a page, a link displays a pop-up box (a div) with additional information. The 'close' element is implemented as a button containing merely the letter 'x'. The property <code>aria-label="close"</code> is used to provide an accessible name to the button.

<pre>    
<style>
    .box-hidden {
        display: none;
        position: absolute;
        top:20%; left:10%; width:30%; height:20%;
        padding: 10px;
        border: 2px solid black;
        background-color: #ddd;
        z-index:1000;
        overflow: auto;
	}
	
    .close-button {
	float:right;
	}
</style>

<p><a onclick="document.getElementById('box').style.display='block'; return true;" href="#box">Display a div box</a></p>
		
<div id="box" class="box-hidden">
   This is a div box.
   <button aria-label="Close" onclick="document.getElementById('box').style.display='none';" class="close-button">X</button>				
</div>
</pre>

Look at [http://www.oturn.net/html-techs/aria-label-2.html  Example close button]

====Example 3: Donation form with controls to change the value of a text input====
A text input is meant to receive the amount the user wants to donate in a multi-step process, with 5 Euros as default. Above and below the text input, buttons allow to increase or decrease the number contained in the text input by 5. The buttons just contain a plus and a minus sign (+ / -), and <code>aria-label</code> attributes provide the labels "step up donation" and "decrease donation".

<pre>
	<script type="text/javascript">	
	function changeValue(e) {
		var inputbox = document.getElementById("donated");
		var currentValue = parseFloat(inputbox.value);
		
		if (e.getAttribute("id") == "stepup") inputbox.value = currentValue + 5;
		else {
			if (currentValue >= 10) inputbox.value = currentValue - 5;
			else inputbox.value = 5;		
		}
	}
	</script>	
	

<form action="javascript:void(0);">
	<label for="donated">Donate:</label>
	<br />
	<button id="stepup" role="button" aria-label="step up donation" onclick="changeValue(this); return false;">+</button>
		
		<input id="donated" type="text" value="5" /> Euro
			
	<button id="stepdown" role="button" aria-label="decrease donation" onclick="changeValue(this); return false;">-</button>
	<input type="submit" value="Next step" />
</form>
</pre>

Look at [http://www.oturn.net/html-techs/aria-label-3.html  Example donation form]

===Resources===
[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/xxxxx.html ARIA-XX: Using aria-label to provide labels for objects.]

===Tests===
====Procedure====
For elements that use aria-label

#Check that the value of the aria-label attribute properly describes the purpose of the focusable element.

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

If this is a sufficient technique for a success criterion, failing this test procedure does not necessarily mean that the success criterion has not been satisfied in some other way, only that this technique has not been successfully implemented and can not be used to claim conformance.