Techniques for WCAG 2.0

Skip to Content (Press Enter)

-

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

Applicability

Technologies that support Accessible Rich Internet Applications (WAI-ARIA).

Editorial Note: This technique will be applicable when Accessible Rich Internet Application specifications reach W3C recommendation status.

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.

IE 8 only supports aria-labelledby with a single id value and it does not support aria-describedby at all.

Description

The purpose of this technique is to demonstrate how to use the WAI-ARIA aria-descibedby property to provide programmatically determined, descriptive information about a user interface element. The aria-descibedby 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 id's.

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: At this time, WAI-ARIA is a Working Draft. This technique is provided as an advisory technique for organizations that wish to experiment with achieving WCAG conformance using WAI-ARIA. When WAI-ARIA becomes a formal specification and is supported in user agents, it is anticipated that this technique will become a sufficient technique.

Examples

Example 1: XHTML

This example is coded in XHTML with a MIME type of application:xhtml+xml. This MIME type is not supported in all user agents. The aria-describedby property is added directly into the XHTML markup, and no additional scripting is needed.

Example Code:

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1
 For Accessible Adaptable Applications//EN"
  "http://www.w3.org/WAI/ARIA/schemata/xhtml-aria-1.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
 <head>
 <meta http-equiv="content-type" content="application:xhtml+xml; charset=utf-8" />
 <title>Demonstration of aria-describedby property</title>
 <style type="text/css">
 div.form p { clear:left; margin: 0.3em 0;}
 .left {
   float:left;
   width:400px;
 }
 .right {
   width:100px;
   text-align:right;
 }
 </style>
 </head>
 <body>
 <p>The buttons on this page use the Accessible Rich Internet Applications aria-describedby property 
 to provide more detailed information about the button action</p>
 <div class="form">
 <p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
 <span class="right"><button id="fontB" onclick="doAction('Fonts');" aria-describedby="fontDesc">
 Fonts </button></span></p>
 <p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
 <span class="right"><button id="colorB" onclick="doAction('Colors');" aria-describedby="colorDesc">
 Colors </button></span></p>
 <p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
 <span class="right"><button id="customB" onclick="doAction('Customize');" aria-describedby="customDesc"> 
 Customize </button></span></p>
 </div>
 </body>
 </html>

Example 2: HTML

This example uses scripting to add an aria-describedby property to buttons on a page. The example creates a buttonIds array variable to hold the ids of the elements that contain description text. The setDescribedBy() function is called from the onload event of the window object.

The setDescribedBy() function loops through all of the button elements and calls setAttribute() on each button element to set the aria-describedby property. Each button's aria-describedby property is set to the id of the element containing its descriptive text.

Using a user agent and/or assistive technology which supports WAI-ARIA, the description will be provided when the user interface controls receive focus.

Example Code:

 <head>
 <meta http-equiv="content-type" content="text/xhtml; charset=utf-8" />
 <title>Demonstration of aria-describedby property</title>
 <style type="text/css">
 div.form p { clear:left; margin: 0.3em 0;}
.left {
  float:left;
  width:400px;
}
.right {
	width:100px;
	text-align:right;
}
 </style>
 <script type="text/javascript">
 //<![CDATA[

 // array entries for each button on the page that associates the button id 
 // with the id of the element containing the text which describes the button
 var buttonIds = new Array();
 buttonIds["fontB"]= "fontDesc";
 buttonIds["colorB"] = "colorDesc";
 buttonIds["customB"] = "customDesc";

 // function that is run after the page has loaded to set the aria-describedBy
 // property on each of the elements referenced by the array of id values
 function setDescribedBy(){
	if (buttonIds){
		var buttons = document.getElementsByTagName("button");
		if (buttons){
			var buttonId;
			for(var i=0; i<buttons.length; i++){
				buttonId = buttons[i].id;
				if (buttonId && buttonIds[buttonId]){
					buttons[i].setAttribute("aria-describedby", buttonIds[buttonId]);
				}
			}
		}
	}
 }

 // simulated action function - currently just displays an alert
 function doAction(theAction){
	alert("Perform the " + theAction + " action");
 }

 window.onload=setDescribedBy;

//]]>
 </script>
 </head>
 <body>
 <p>The buttons on this page use the Accessible Rich Internet Applications 
 aria-describedby property to provide more detailed information 
 about the button action.
 </p>
 <div class="form">
 <p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
    <span class="right"><button id="fontB" onclick="doAction('Fonts');"> Fonts </button></span>
 </p>
 <p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
    <span class="right"><button id="colorB" onclick="doAction('Colors');"> Colors </button></span>
 </p>
 <p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
    <span class="right"><button id="customB" onclick="doAction('Customize');"> Customize </button></span>
 </p>
 </div>
 </body>

Resources

Resources are for information purposes only, no endorsement implied.

Tests

Procedure

  1. Check that there is an input 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 input control.

Expected Results