View source for ARIA1: Using the aria-describedby property to provide a descriptive label for user interface controls

== Status ==
* Added to XML by AWK Dec 20, 2013
See  [http://www.w3.org/WAI/GL/WCAG20-TECHS/ARIA1.html ARIA1: Using the aria-describedby property to provide a descriptive label for input controls] for the current version of this technique.

Does the newly added Example 2 "Landmark Descriptions" fit here or would it be better under [http://www.w3.org/WAI/GL/wiki/Using_aria-describedby_to_provide_descriptions_of_objects Using aria-describedby to provide descriptions of objects]?

Should these two aria-describedby techniques be combined?


[https://www.w3.org/2002/09/wbs/35422/20130926ttf/results Surveyed by TF 26 September 2013]

* Moved examples from "Using aria-describedby to provide descriptions of objects" to this technique
* Changed "input controls" to "user interface controls"
* Dropped 2.4.4 from Applicability

== Applicability ==

Technologies that support [http://www.w3.org/TR/wai-aria/ Accessible Rich Internet Applications (WAI-ARIA)].

This technique relates to:

* [http://www.w3.org/TR/2008/REC-WCAG20-20081211/#content-structure-separation-programmatic Success Criterion 1.3.1 (Info and Relationships)]
* [http://www.w3.org/TR/2008/REC-WCAG20-20081211/#minimize-error-cues Success Criterion 3.3.2 (Labels or Instructions)]

== User Agent and Assistive Technology Support Notes ==

See [http://www.w3.org/WAI/GL/WCAG20-TECHS/wai-aria_notes.html#wai-aria_ua_support User Agent Support for WAI-ARIA] for general information on user agent support.

== Description ==

The purpose of this technique is to demonstrate how to use the WAI-ARIA [http://www.w3.org/TR/wai-aria/states_and_properties#aria-describedby <code>aria-describedby</code>] property to provide programmatically determined, descriptive information about a user interface control. A description is intended to provide additional detail that some users might need whereas a label provides the user with the essence of what the object does. Note that a label is still required even if a user provides a description. The <code>aria-describedby</code> property may be used to attach descriptive information to one or more elements through via an ID reference. This is normally a single value, but can also reference more than one element by separating ID references in the attribute with whitespace. 

Note:  The <code>aria-describedby</code> property is not designed to reference descriptions on an external resource — since it is an ID, it must reference an element in the same DOM document.

== Examples ==

==== Example 1: Using aria-describedby property to describe a Close button's action ====
A button that functions as a 'close' button on a dialog is described elsewhere in the document. The aria-describedby property is used to associate the description with the link.  This example taken from 

<pre>
<button aria-label="Close" aria-describedby="descriptionClose" 
    onclick="myDialog.close()">X</button>

...

<div id="descriptionClose">Closing this window will discard any information entered and 
return you back to the main page</div>
</pre>

====Example 2: Using aria-describedby to associate instructions with form fields====
Sample form field using <code>aria-describedby</code> to associate instructions with form fields while there is a form label.
<pre>    
<form> 
<label for="fname">First name</label>  
<input name="" type="text" id="fname" aria-describedby="int2"> 
<p id="int2">A  bit of instructions for this field linked with aria-describedby. </p>
</form>
</pre>

[http://3needs.org/en/testing/code/aria-describedby-close.html See example]

==== Example 3: Using aria-describedby property to provide more detailed information about the button ====

<pre>
<p><span id="fontDesc">Select the font faces and sizes to be used on this page</span>
 <button id="fontB" onclick="doAction('Fonts');" aria-describedby="fontDesc"> Fonts </button>
</p>
<p><span id="colorDesc">Select the colors to be used on this page</span>
 <button id="colorB" onclick="doAction('Colors');" aria-describedby="colorDesc"> Colors </button>
</p>
<p><span id="customDesc">Customize the layout and styles used on this page</span>
 <button id="customB" onclick="doAction('Customize');" aria-describedby="customDesc"> Customize </button>
</p>
</pre>

==== Example 4: Using aria-describedby associate tooltips with form fields====
The following code snippet from the [http://test.cita.uiuc.edu/aria/tooltip/tooltip1.php iCITA] site shows how to use <code>aria-describedby</code> and the onfocus="tooltipShow() function to display the tooltip when focus is placed on an element. 

<pre>
<html lang="en-us"">  
<head>    
   <title>inline: Tooltip Example 1</title>      
   <link rel="stylesheet" href="css/tooltip1_inline.css"  type="text/css">    
   <script type="text/javascript" src="js/tooltip1_inline.js"></script>    
   <script type="text/javascript" src="../js/widgets_inline.js"></script>
   <script type="text/javascript" src="../js/globals.js"></script>          
   <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon">    
   <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon"> 
</head>
   ...   

   <body onload="initApp()">

   <div id="container">

   <h1>Tooltip Example 1</h1>
     <h2>Create Account</h2>
   <div class="text">
   <label for="first">First Name:</label> 

   <input type="text"  id="first" name="first" size="20" 
          onmouseover="tooltipShow(event, this, 'tp1');"     
          onfocus="tooltipShow(event, this,  'tp1');" 
          aria-describedby="tp1"  		 
          aria-required="false"/>

   <div id="tp1" role="tooltip" aria-hidden="true">Your first name is optional. </div>    
   </div>

</pre>

== Resources ==

Resources are for information purposes only, no endorsement implied.

* [http://www.w3.org/WAI/intro/aria WAI-ARIA Overview]
* [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]
* [https://developer.mozilla.org/en-US/docs/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute Using the aria-describedby attribute MDN]

== Related Techniques ==
http://www.w3.org/WAI/GL/wiki/Using_aria-describedby_for_link_purpose

== Tests ==
==== Procedure ====

# Check that there is a user interface control having an aria-describedby attribute that references one or more elements via unique id.
# Check that the referenced element or elements provide additional information about the user interface control.

==== Expected Results ====

Tests #1 and #2 are true.