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

The purpose of this technique is to demonstrate how to use the WAI-ARIA aria-describedby property to provide programmatically determined, descriptive information about a user interface element. The aria-describedby property may be used to attach descriptive information to one or more elements through the use of an id reference list. The id reference list contains one or more unique element ids.

Refer to Supporting ARIA in XHTML and HTML 4.01 for information on how to provide WAI-ARIA States and Properties with XHTML and HTML. WAI-ARIA States and Properties is compatible with other languages as well; refer to documentation in those languages.

Note: The aria-describedby 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.

<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>

Working example: Example 1

Example 2: Using aria-describedby to associate instructions with form fields

Sample form field using aria-describedby to associate instructions with form fields while there is a form label.

 <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>

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

<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>

Example 4: Using aria-describedby to associate tooltips with form fields

The following code snippet from the iCITA site shows how to use aria-describedby and the onfocus="tooltipShow() function to display the tooltip when focus is placed on an element.

<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>

Resources

Related Techniques

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

Checks #1 and #2 are 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.

Techniques are Informative

Techniques are informative—that means they are not required. The basis for determining conformance to WCAG 2.0 is the success criteria from the WCAG 2.0 standard—not the techniques. For important information about techniques, please see the Understanding Techniques for WCAG Success Criteria section of Understanding WCAG 2.0.