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

From WCAG WG

Status

  • Added to XML by AWK Dec 20, 2013

See 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 Using aria-describedby to provide descriptions of objects?

Should these two aria-describedby techniques be combined?


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 Accessible Rich Internet Applications (WAI-ARIA).

This technique relates to:

User Agent and Assistive Technology Support Notes

See 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 aria-describedby 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 aria-describedby 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 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. This example taken from 

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

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>

See example

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

Resources are for information purposes only, no endorsement implied.

Related Techniques

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

Tests

Procedure

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

Expected Results

Tests #1 and #2 are true.

Retrieved from "https://www.w3.org/WAI/GL/wiki/index.php?title=ARIA1:_Using_the_aria-describedby_property_to_provide_a_descriptive_label_for_user_interface_controls&oldid=3696"