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 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>
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.
- WAI-ARIA Overview
- WAI ARIA 1.0 Authoring Practices
- HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation
- 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.