Techniques for WCAG 2.0

# ARIA Techniques for WCAG 2.0

This Web page lists ARIA Techniques from Techniques for WCAG 2.0: Techniques and Failures for Web Content Accessibility Guidelines 2.0. For information about the techniques, see Introduction to Techniques for WCAG 2.0. For a list of techniques for other technologies, see the Table of Contents.

## ARIA1: Using Accessible Rich Internet Application describedby property to provide a descriptive, programmatically determined label

### Applicability

HTML and XHTML with scripting and Accessible Rich Internet Applications.

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

This technique relates to:

- Success Criterion 1.3.1 (Info and Relationships)
  - How to Meet 1.3.1 (Info and Relationships)
  - Understanding Success Criterion 1.3.1 (Info and Relationships)
- Success Criterion 2.4.4 (Link Purpose (In Context))
  - How to Meet 2.4.4 (Link Purpose (In Context))
  - Understanding Success Criterion 2.4.4 (Link Purpose (In Context))
- Success Criterion 2.4.2 (Page Titled)
  - How to Meet 2.4.2 (Page Titled)
  - Understanding Success Criterion 2.4.2 (Page Titled)
- Success Criterion 3.3.2 (Labels or Instructions)
  - How to Meet 3.3.2 (Labels or Instructions)
  - Understanding Success Criterion 3.3.2 (Labels or Instructions)

### User Agent and Assistive Technology Support Notes

As of October, 2006, Accessible Rich Internet Application techniques are supported in Firefox 1.5 or later on Windows and Window-Eyes version 5.5 or later. Support in other user agents and assistive technologies is in progress. This particular technique relies on updates made to Firefox 2.0 to allow the use of the `describedby` attribute by itself without also defining a role for the element.

### Description

The purpose of this technique is to demonstrate how to use the Accessible Rich Internet Application (ARIA) `descibedby` property to provide descriptive information about a user interface control that can be programmatically determined by user agents. ARIA techniques provide the ability to add programmatically determined information to an element which can provide additional information about the element. The user agent can provide this additional information to assistive technology for presentation to the user. For example, the `describedby` property can be used to provide information that is available in the content surrounding the user interface control but would not normally be available when the user is navigating from control to control using an assistive technology.

### Examples

#### Example 1: HTML

This example uses scripting to add the `describedby` property to user interface controls on the page. The use of scripting is necessary because the "describedby" attribute is not in the HTML specification and adding it directly to the markup would prevent the markup from validating. In user agents which support namespaces, the required state is assigned using the `setAttributeNS()` application programming interface (API). For other user agents the required state is assigned using the `setAttribute()` API and the namespace is simulated by adding a static text string to the front of the `describedby` attribute.

In the example below two array variables, `buttonIds` and `linkIds`, are created. Each array holds the ids of the elements that contain the description text. Each array is indexed via the id of the elements which need a `describedby` property. The `setDescribedBy()` function is called from the onload event of window object.

The `setDescribedBy()` function finds all of the button elements on the page. It loops through all of the button elements found and, using the button id as the index, looks in the `buttonIds` array for an associated id value. This id is the `id` attribute of the element which contains the description text to be associated with the button. If an associated id is found, the script assigns the `describedby` property to the button using the `setAttrNS()` function.

The `setDescribedBy()` function also finds all of the anchor elements on the page and performs a similar process. It looks for associated ids in the `linksId` array and assigns the `describedby` property to each link using the `setAttrNS()` function.

The `setAttrNS()` function will call the `setAttributeNS()` API when it is available to set the required attribute. It uses the appropriate namespace URI, "http://www.w3.org/2005/07/aaa", for the States and Properties Module for Accessible Rich Internet Applications (ARIA States and Properties). If the `setAttributeNS()` API is not available in the user agent, a static, simulated namespace of "aaa:" is added to the required attribute name and it is set using the `setAttribute()` API.

Using a user agent and/or assistive technology which supports ARIA, the additional 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 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";
     // array entries for each link on the page that associates the link id with
     // the id of the element containing the text which describes the link
     var linkIds = new Array();
     linkIds["iceberg"] = "icebergInfo";

     // function that is run after the page has loaded to set the 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]){
    					setAttrNS(buttons[i], "describedby", buttonIds[buttonId]);
    				}
    			}
    		}
    	}
    	if (linkIds){
    		var links = document.getElementsByTagName("a");
    		if (links){
    			var linkId;
    			for(var k=0; k<links.length; k++){
    				linkId = links[k].id;
    				if (linkId && linkIds[linkId]){
    					setAttrNS(links[k], "describedby", linkIds[linkId]);
    				}
    			}
    		}
    	}
     }

     // method to set the attribute values based on the capability of the browser.
     // Use setAttributeNS if it is available, otherwise append a namespace
     // indicator string to the attribute and set its value.
     function setAttrNS(elemObj, theAttr, theValue){
             elemObj.setAttribute("aria-" + theAttr, theValue);
     }

     // 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
     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>
     <p>The link in this paragraph has been updated with the Accessible Rich
     Internet Applications describedby property to provide more information
     about the link</p>
     <p> <span id="icebergInfo">Alaskan storm cracks iceberg in Antarctica. </span>
     A bad storm in Alaska last October generated an ocean swell that broke apart
     a giant iceberg near Antarctica six days later, U.S. researchers reported on Monday.
     <a href="http://www.sciencemag.com/iceberg.html" id="iceberg">More Info...</a>.
     </p>
     </body>

Working HTML example of use of describedy property

#### Example 2: XHTML

This is the same example coded in XHTML with a MIME type of application:xhtml+xml. This MIME type is not supported in all user agents. It declares an xml namespace to access the `describedby` property. The `describedby` information 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//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
     xmlns:waistate="http://www.w3.org/2005/07/aaa" >
     <head>
     <meta http-equiv="content-type" content="application:xhtml+xml; charset=utf-8" />
     <title>Demonstration of 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 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');" waistate: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');" waistate: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');"
     waistate:describedby="customDesc"> Customize </button></span></p>
     </div>
     <p>The link in the next paragraph has been updated with the Accessible Rich Internet Applications
     describedby property to provide more information about the link</p>
     <p> <span id="icebergInfo">Alaskan storm cracks iceberg in Antarctica. </span>
     A bad storm in Alaska last October generated an ocean swell that broke apart a giant
     iceberg near Antarctica six days later, U.S. researchers reported on Monday.
     <a href="http://www.sciencemag.com/iceberg.html" id="iceberg" waistate:describedby="icebergInfo">More Info...</a>.
     </p>
     </body>
     </html>

### Resources

Resources are for information purposes only, no endorsement implied.

- Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap)

- Accessible Rich Internet Applications (WAI-ARIA) Version 1.0

### Related Techniques

- ARIA4: Using Accessible Rich Internet Applications to programmatically identify form fields as required

### Tests

#### Procedure

1. Load the page using a user agent and/or assistive technology that supports Accessible Rich Internet Applications.

2. Using a user agent that supports ARIA, navigate to each user interface control modified with a `describedby` property and verify that the description is made available to the user.

#### Expected Results

- Check #2 is true.

## ARIA2: Identifying required fields with the "required" property

### Applicability

Technologies that support States and Properties for Accessible Rich Internet Applications.

This technique relates to:

- Success Criterion 3.3.3 (Error Suggestion)
  - How to Meet 3.3.3 (Error Suggestion)
  - Understanding Success Criterion 3.3.3 (Error Suggestion)

### User Agent and Assistive Technology Support Notes

WAI-ARIA is partially supported in Firefox 2.0, which maps roles and properties to platform accessibility APIs. JAWS and Window-Eyes have been successfully tested presenting these properties to the user. FireVox, a self-voicing extension to Firefox, also supports WAI-ARIA via direct DOM access.

At this time, there is not additional user agent support.

### Description

The objective of this technique is to indicate that the completion of a user input field is mandatory in a programmatically determinable way. The WAI-ARIA required state indicates that user input is required before submission. The "required" state can have values of "true" or "false". For example, if a user must fill in an address field, then "required" is set to true.

Note: The fact that the element is required is often visually presented (such as a sign or symbol after the control). Using the "required" property makes it much easier for user agents to pass on this important information to the user in a user agent-specific manner.

WAI-ARIA States and Properties is a module supported in XHTML 1.1 and higher, and the specification documents how to provide the properties in XHTML and other XML-based languages. Refer to Embedding Accessibility Role and State Metadata in HTML Documents for information on how to provide WAI-ARIA States and Properties with HTML and XHTML 1.0. 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, this technique is anticipated to become a sufficient technique.

### Examples

#### Example 1: A required text input field in XHTML

The following source code shows an XHTML document using the "required" property to indicate that a form field must be submitted. The mandatory nature of the field is also indicated in the label as a fallback for user agents that do not support ARIA.

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/2005/07/aaa/xhtml11-aaa.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml"
              xmlns:aaa="http://www.w3.org/2005/07/aaa"
              xml:lang="en">
      <head>
        <title>Required Input</title>
      </head>
      <body>
        <h1>Required Input</h1>
        <p>The following form input field must be completed by the user
        before the form can be submitted.</p>
        <form action="http://example.com/submit">
          <p>
            <label for="test">Test (required)</label>
            <input name="test" id="test" aaa:required="true" />
          </p>
          <p>
            <input type="submit" value="Submit" />
          </p>
        </form>
      </body>
    </html>

### Resources

Resources are for information purposes only, no endorsement implied.

- States and Properties Module for Accessible Rich Internet Applications

- Embedding Accessibility Role and State Metadata in HTML Documents

### Related Techniques

- ARIA3: Identifying valid range information with the "valuemin" and "valuemax" properties

### Tests

#### Procedure

1. Access a page with mandatory form fields in a user agent that supports the Accessible Rich Internet Applications specification.

2. Leaving mandatory form fields empty, attempt to submit the form.

3. Check that that the user agent notifies of the missing information.

4. Provide values for the mandatory fields.

5. Check that the user agent allows form submission to proceed.

#### Expected Results

- #3 and #5 are true

## ARIA3: Identifying valid range information with the "valuemin" and "valuemax" properties

### Applicability

Technologies that support States and Properties for Accessible Rich Internet Applications.

This technique relates to:

- Success Criterion 3.3.3 (Error Suggestion)
  - How to Meet 3.3.3 (Error Suggestion)
  - Understanding Success Criterion 3.3.3 (Error Suggestion)

### User Agent and Assistive Technology Support Notes

WAI-ARIA is partially supported in Firefox 2.0, which maps roles and properties to platform accessibility APIs. JAWS and Window-Eyes have been successfully tested presenting these properties to the user. FireVox, a self-voicing extension to Firefox, also supports WAI-ARIA via direct DOM access.

At this time there is not additional user agent support.

### Description

The objective of this technique is to provide information about the allowable range of an entry field in a programmatically determinable way. The WAI-ARIA valuemin and valuemax states provide the minimum and maximum (respectively) values that may be provided by the user. User agents will not permit users to enter values outside that range, or will generate a validation error if users do so.

WAI-ARIA States and Properties is a module supported in XHTML 1.1 and higher, and the specification documents how to provide the properties in XHTML and other XML-based languages. Refer to Embedding Accessibility Role and State Metadata in HTML Documents for information on how to provide WAI-ARIA States and Properties with HTML and XHTML 1.0. 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, this technique is anticipated to become a sufficient technique.

### Examples

#### Example 1: A text entry field that accepts dates during the year 2007

The following text entry field requires the user to enter a date value with a value during the year 2007:

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/2005/07/aaa/xhtml11-aaa.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:aaa="http://www.w3.org/2005/07/aaa"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema-datatypes"
      xml:lang="en">
    <head>
      <title>Date Entry</title>
    </head>
    <body>
      <h1>Date Entry</h1>
      <p>Text entry accepts a date in the year 2007.</p>
      <form action="http://example.com/submit">
        <p><label for="test">Enter a date in 2007:</label>
        <input name="test" id="test"
          aaa:valuemin="2007-01-01" aaa:valuemax="2007-12-31"
          aaa:datatype="xsd:date" /></p>
        <p><input type="submit" value="Submit" /></p>
      </form>
    </body>
    </html>

#### Example 2: A spinner control that provides values between 1 and 100

The following spin button allows users to enter a number between 1 and 100.

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/2005/07/aaa/xhtml11-aaa.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:wairole="http://www.w3.org/2005/01/wai-rdf/GUIRoleTaxonomy#"
      xmlns:aaa="http://www.w3.org/2005/07/aaa"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema-datatypes"
      xml:lang="en">
    <head>
      <title>Spin Button</title>
    </head>
    <body>
      <h1>Spin Button</h1>
      <p>Spin button allows users to enter a number between 1 and 100. It is
        implemented as a text input, to which user agents that do not support
        ARIA roles fall back.</p>
      <form action="http://example.com/submit">
        <p><label for="test">Enter a number between 1 and 100</label>
        <input name="test" id="test" role="wairole:spinbutton"
          aaa:valuemin="1" aaa:valuemax="100" aaa:datatype="xsd:integer" /></p>
        <p><input type="submit" value="Submit" /></p>
      </form>
    </body>
    </html>

### Resources

Resources are for information purposes only, no endorsement implied.

- States and Properties Module for Accessible Rich Internet Applications

- XML Schema Part 2: Datatypes

- Embedding Accessibility Role and State Metadata in HTML Documents

### Related Techniques

- ARIA2: Identifying required fields with the "required" property

### Tests

#### Procedure

1. Access a page with form fields that require data in a certain range, using a user agent that supports the Accessible Rich Internet Applications specification.

2. Provide information that is outside the allowable range, and attempt to submit the form.

3. Check that the user agent notifies of the invalid data.

4. Provide information that is inside the allowable range, and attempt to submit the form.

5. Check that the user agent accepts the data and allows the submit to proceed.

#### Expected Results

- #3 and #5 are true

## ARIA4: Using Accessible Rich Internet Applications to programmatically identify form fields as required

### Applicability

HTML and XHTML with scripting and Accessible Rich Internet Application support.

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

This technique relates to:

- Success Criterion 1.3.1 (Info and Relationships)
  - How to Meet 1.3.1 (Info and Relationships)
  - Understanding Success Criterion 1.3.1 (Info and Relationships)
- Success Criterion 3.3.2 (Labels or Instructions)
  - How to Meet 3.3.2 (Labels or Instructions)
  - Understanding Success Criterion 3.3.2 (Labels or Instructions)

### User Agent and Assistive Technology Support Notes

As of January 2007, the current version of the Accessible Rich Internet Application (ARIA) specification is supported in Firefox 1.5 or later on Windows using Window-Eyes version 5.5 or later and partially supported using JAWS 8.0 or later. Support in other user agents and assistive technologies is in progress. Since ARIA is not yet supported in all technologies, it is important to also use other sufficient techniques to mark a field as required. This particular technique relies on updates made to Firefox 2.0 to allow the use of the required attribute by itself without also defining a role for the element.

### Description

The purpose of this technique is to demonstrate how to use Accessible Rich Internet Applications to programmatically identify form components for which user input or selection are required. Accessible Rich Internet Applications techniques provide the ability to add additional information about elements which can be programmatically determined. The user agent can provide this additional information to assistive technology for presentation to the user.

### Examples

#### Example 1

This example uses scripting to add the required state to a form element. In user agents which support namepaces, the required state is assigned using the `setAttributeNS()` application programming interface (API). For other user agents the required state is assigned using the `setAttribute()` API and the namespace is simulated by adding a static text string to the front of the required attribute.

In the example below an array variable, requiredIds, is created with the ids of the elements which need to marked as required. The `setRequired()` function is called from the `onload` event of window object.

The `setRequired()` function loops through all of the ids provided, retrieves the element and assigns the required state of true using the `setAttrNS()` function.

The `setAttrNS()` function will call the `setAttributeNS()` API when it is available to set the required attribute. It uses the appropriate namespace URI, "http://www.w3.org/2005/07/aaa", for the Accessible Rich Internet Applications States and Properties Module. If the `setAttributeNS()` API is not available in the user agent, a static, simulated namespace of, "aaa:" is added to the required attribute name and it is set using the setAttribute() API.

When this page is accessed using Firefox 2.0 or later or Window-Eyes 5.5 or later, Window-Eyes will speak "required" when reading the label for the input fields.

Example Code:

    <head>
     <script type="text/javascript">
     //<![CDATA[

     // array or ids on the required fields on this page
     var requiredIds = new Array( "firstName", "lastName");

     // function that is run after the page has loaded to set the required role on each of the
     //elements in requiredIds array of id values
     function setRequired(){
     	if (requiredIds){
     		var field;
     		for (var i = 0; i< requiredIds.length; i++){
     			field = document.getElementById(requiredIds[i]);
     			setAttrNS(field, "required", "true");
     		}
     	}
     }

     // method to set the attribute values based on the capability of the browser.
     // Use setAttributeNS if it is available,
     // otherwise append a namespace indicator string to the attribute and set its value.
     function setAttrNS(elemObj, theAttr, theValue){
     	if (typeof document.documentElement.setAttributeNS != 'undefined') {
     		elemObj.setAttributeNS("http://www.w3.org/2005/07/aaa", theAttr, theValue);
     	}else{
     		elemObj.setAttribute("aaa:" + theAttr, theValue);
     	}
     }
     window.onload=setRequired;
    //]]>
     </script>
     </head>
     <body>
     <p>Please enter the following data.  Required fields have been programmatically identified
     as required and  marked with an asterisk (*) following the field label.</p>
     <form action="submit.php">
     <p>
     <label for="firstName">First Name *: </label><input type="text" name="firstName"
        id="firstName" value="" />
     <label for="lastName">Last Name *: </label><input type="text" name="lastName"
        id="lastName"  value="" />
     </p>
     </form>
     </body>

### Resources

Resources are for information purposes only, no endorsement implied.

- Roadmap for Accessible Rich Internet Applications (ARIA Roadmap)

- Roles for Accessible Rich Internet Applications (ARIA Roles)

- States and Properties Module for Accessible Rich Internet Applications (ARIA States and Properties)

### Related Techniques

(none currently listed)

### Tests

#### Procedure

1. Load the page using an user agent and/or assistive technology that supports Accessible Rich Internet Applications.

2. Navigate to each required form element and verify that "required" is spoken.

#### Expected Results

- Check #2 is true