For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)

Note: This success criterion is primarily for authors who develop or script their own user interface components. Standard HTML controls already meet this success criterion when used according to specification.

Refer to Understanding SC 4.1.2 for more information (external link to WCAG).

Rationale

The purpose of this checkpoint is to ensure that Assistive Technologies (AT) can gather information about, activate (or set), and receive status of all user interface components.

Custom widgets often do not expose proper role, state and property information needed for assistive technologies. As a result, people with disabilities have difficulty identifying and interacting with the widgets. Common examples are menus, trees, data grids, accordions, and dialog boxes. Ensuring proper markup and keyboard operation enables people with disabilities to identify and interact with the widgets in the same manner they identify and interact with standard application widgets.

Note: When developers use standard controls from accessible technologies and they develop the user interface elements according to specification, the application will most likely meet this checkpoint's requirements. This checkpoint is primarily for software developers who develop or use custom user interface components.

Development Techniques

Review the General techniques as well as other tabs applicable to your technology.  Prioritize the use of technology-specific techniques, and implement the General techniques as needed. You are always required to find, understand and implement accessible code techniques to meet the checkpoint. The documented techniques and supplements are not exhaustive; they illustrate acceptable ways to achieve the spirit of the checkpoint. If numbered, techniques are in order of preference, with recommended techniques listed first. Where used, IBM information that complements the WCAG techniques is indicated as supplemental.

General techniques

Instructions: Select the situation below that matches your content. Any item in the described situation represents a technique that is deemed sufficient for meeting this checkpoint. Ensure you review WCAG Common Failures to avoid development mistakes.

Situation A: If using a standard user interface component in a markup language (e.g., HTML)

  1. G108: Using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes

Situation B: If using script or code to re-purpose a standard user interface component in a markup language

  1. Exposing the names and roles, allowing user-settable properties to be directly set, and providing notification of changes using one of the technology-specific techniques that follow.

Situation C: If using a standard user interface component in a programming technology

  1. G135: Using the accessibility API features of a technology to expose names and roles, to allow user-settable properties to be directly set, and to provide notification of changes

Situation D: If creating your own user interface component in a programming language

  1. G10: Creating components using a technology that supports the accessibility API features of the platforms on which the user agents will be run to expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes

Web (HTML, ARIA, CSS) techniques

Instructions: In addition to the General techniques, any of these Web techniques are deemed sufficient in the following situations when used as instructed. Where numbered, techniques are ordered from most to least preferred.

Situation A: If using a standard user interface component in a markup language (e.g., HTML):

  1. Meeting G108: Using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes with the following:
  2. ARIA16: Using aria-labelledby to provide a name for user interface controls (see ARIA16 supplement)
  3. ARIA14: Using aria-label to provide an invisible label where a visible label cannot be used (see ARIA16 supplement)

Situation B: If using script or code to re-purpose a standard user interface component in a markup language:

Situation D: If creating your own user interface component in a programming language:

Web supplements

The following examples and comments provide additional information beyond that available in the WCAG techniques. Where items supplement existing techniques, they are numbered accordingly (e.g., ARIA4). ARIA 1.1 updates for roles and properties have been included.

ARIA16 Using aria-labelledby to provide a name for user interface control

The following example shows a tree labeled with an aria-labelledby. However, the tree item's accessible name is specified with the inner text of the tree item element.

<h1 id="contents">Table of contents</h1>
...
<div role="tree" aria-labelledby="contents">
<div role="treeitem">
Chapter 1 - Introduction
</div>
...
</div>

The following table contains a list of WAI-ARIA widgets that must have an accessible name. The second column indicates whether a widget's accessible name may be specified by an aria-label, aria-labelledby or a widget's inner text.

WAI-ARIA widgets that have an accessible name
WAI-ARIA widget role Widget may be labelled by one of the following
alert aria-label, aria-labelledby
alertdialog aria-label, aria-labelledby
button aria-label, aria-labelledby, widget's inner text
checkbox aria-label, aria-labelledby, widget's inner text
combobox aria-label, aria-labelledby
dialog aria-label, aria-labelledby
grid aria-label, aria-labelledby
gridcell aria-label, aria-labelledby, widget's inner text
link aria-label, aria-labelledby, widget's inner text
listbox aria-label, aria-labelledby
log aria-label, aria-labelledby
marquee aria-label, aria-labelledby
menu aria-label, aria-labelledby
menubar aria-label, aria-labelledby
menuitem aria-label, aria-labelledby, widget's inner text
menuitemcheckbox aria-label, aria-labelledby, widget's inner text
menuitemradio aria-label, aria-labelledby, widget's inner text
option aria-label, aria-labelledby, widget's inner text
progressbar aria-label, aria-labelledby
radio aria-label, aria-labelledby, widget's inner text
radiogroup aria-label, aria-labelledby
scrollbar aria-label, aria-labelledby
searchbox aria-label, aria-labelledby
slider aria-label, aria-labelledby
spinbutton aria-label, aria-labelledby
switch aria-label, aria-labelledby
tab aria-label, aria-labelledby, widget's inner text
tabpanel aria-label, aria-labelledby
textbox aria-label, aria-labelledby
timer aria-label, aria-labelledby
tooltip aria-label, aria-labelledby, widget's inner text
tree aria-label, aria-labelledby
treegrid aria-label, aria-labelledby
treeitem aria-label, aria-labelledby, widget's inner text

ARIA4: Using a WAI-ARIA role to expose the role of a user interface component

Standard HTML controls expose role and state information to assistive technologies through the Microsoft Active Accessibility technology. However, standard HTML controls that are repurposed into custom widgets, such as trees, menus and grids, have no mechanism to expose role and state.

WAI-ARIA provides a mechanism to expose custom widget role and state information by assigning role and state properties to standard HTML elements. For example, the following code fragment repurposes an HTML list into a tree by assigning a tree role to the <ul> element. The <li> element containing fruits is repurposed into a tree node by assigning a role="treeitem" attribute to it. When a blind user navigates to the fruits node, a screen reader announces that the fruits node is expanded.

<ul id="tree1" role="tree" tabindex="0">
<li role="treeitem" tabindex="-1" aria-expanded="true" aria-selected="true" onkeydown="navKey">
Fruits
</li>
...
</ul>

Note that a non-form or non-anchor element having an event handler must have a valid WAI-ARIA role. In the preceding example, the first list item has an event handler associated with it. Therefore, the element must also have a WAI-ARIA role associated with it. If the element contained only the onkeydown attribute and no role attribute it would fail to comply with this checkpoint.

WAI-ARIA roles can also address custom dialog widgets developed with CSS and JavaScript, which do not expose correct role, state and property information to assistive technologies. For example, blind users often have difficulty determining the presence of a DHTML dialog box because a screen reader announces nothing when the dialog box is rendered.

The following example demonstrates the use of the WAI-ARIA roles dialog and heading to inform assistive technologies that the JavaScript/CSS widget is a dialog box. Use the WAI-ARIA aria-labelledby and level properties to label the dialog box and indicate that the label is a level one heading.

<input type="button" onclick="showDialog();" value="Show dialog" id="dialogOpen">
<div style="padding: 10px; display: block;" aria-labelledby="dialogLabel" role="dialog" id="dialogContainer" class="dialogContainer">
      <div style="width: 260px;" id="dialog1" class="dialogBody">
        <div class="header"> <span role="heading" id="dialogLabel" class="headertext" aria-level="1">Personal information</span> </div>
        <form>
          <div style="padding: 5px;">
            <label for="firstName"> First name: </label>
            <input type="text" name="firstName" id="firstName">
          </div>
          <div style="padding: 5px;">
            <label for="lastName"> Last name: </label>
            <input type="text" name="lastName" id="lastName">
          </div>
          <div style="padding: 5px;">
            <label for="phone"> Phone number: </label>
            <input type="text" name="phone" id="phone">
          </div>
          <div style="padding-top: 10px; margin-left: 5px;">
            <input type="button" onclick="hideDialog();" value="Submit" id="dialogClose">
          </div>
        </form>
      </div>
    </div>

For more examples on assigning roles and states to custom widgets in order to implement this technique, see the WAI-ARIA specification and WAI-ARIA Authoring Practices.

Using required child and parent roles and required properties for specific WAI-ARIA widgets

The first two tables below contain required child and parent roles for specific WAI-ARIA widgets. The last table contains required properties for WAI-ARIA widgets. All of the required roles and properties in the right column of each table must be implemented for each of the roles in the left column.

The following table contains specific WAI-ARIA roles that require child elements:

WAI-ARIA roles that require child elements
Role Required child
combobox v1.0 listbox or textbox
combobox v1.1 textbox or searchbox (when either is expanded, add listbox or tree or grid or dialog)
grid row or rowgroup>row
list listitem or group>listitem
listbox option
menu menuitem or menuitemcheckbox or menuitemradio or group>menuitemradio
radiogroup radio
row gridcell or columnheader or rowheader or cell
tablist tab
tree treeitem or group>treeitem
treegrid row or rowgroup>row
 

The following table contains specific WAI-ARIA roles that require parent container elements:

 
WAI-ARIA roles that require parent container elements
Role Required parent container
columnheader row
gridcell row
listitem list or group
menuitem menu or menubar or group
menuitemcheckbox menu or menubar
menuitemradio menu or menubar or group
option listbox
row grid or treegrid or rowgroup or table
rowgroup grid or table or treegrid
rowheader row
tab tablist
treeitem tree or group
 

The following table contains WAI-ARIA widget roles that have required properties:

 
WAI-ARIA widget roles that have required properties
Role Required property
checkbox aria-checked
combobox 1.0 aria-expanded
combobox 1.1 aria-expanded, aria-controls place on the "owned" textbox element
menuitemcheckbox aria-checked
menuitemradio aria-checked
option aria-selected
progressbar recommended: aria-valuenow and aria-valuemax and aria-valuemin
radio aria-checked
scrollbar aria-controls and aria-orientation and aria-valuenow and aria-valuemax and aria-valuemin
slider aria-valuemax and aria-valuenow and aria-valuemin
spinbutton aria-valuemax and aria-valuenow and aria-valuemin
switch aria-checked

Making dynamic content accessible to screen reader users

Until the introduction of WAI-ARIA, providing notifications of changes for dynamic Web content that changes frequently, such as stock ticker quotes or news feeds, was difficult. As a result, dynamic content was often completely inaccessible to screen reader users. With the advent of ARIA live regions, Web application developers can easily make dynamic content accessible to screen reader users.

Refer to the ARIA 1.1 aria-live property as well as various topics concerning live regions in the WAI-ARIA Best Practices.

Mobile (iOS) techniques

Instructions: In addition to the General techniques, the Mobile Native iOS techniques in this section represent a technique or combination of techniques deemed sufficient for meeting this checkpoint (4.1.2).

Note: These techniques and examples also appear in, and are relevant to, the CI 162 Checklist, Checkpoint 502.3.1 - Object Information and Checkpoint 502.3.4 - Values.

Use the accessibility API features of a technology

Using the accessibility API features, you can expose names and roles, allow user-settable properties to be directly set, and provide notification of changes.

Software can extend or modify the behavior of standard iOS UI controls to create a custom control by subclassing, or superclassing the standard control. The custom control created may or may not be accessible depending on how the software modified the base control to create the appearance and behavior of the custom control. Software must verify the accessible name, role, state, and, if applicable, value are accessible. This can be done using Accessibility Inspector in the xCode development environment.

Software that creates custom controls must support the UI Accessibility Protocol to expose the object label, focus location, accessibility enabled status, value, traits (roles), and status changes. Developers should refer to the Accessibility Programming Guide for iOS.

A training module on accessibility for custom controls on iOS is available on iTunesU. Search for Stanford University Course CS193D “Developing Apps for iOS," 2010 Sessions, Lecture 18: “Accessibility on iOS: Make an App for Everyone,” guest lecturer Chris Fleizach, Apple Accessibility Development team.

Use components to support accessibility API

Create components using a technology that supports the accessibility API features of the user agents' target platforms to expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes.

When using the standard iOS controls, developers must set the accessibility attribute of the control.

In Interface Builder, this is done by selecting the Accessibility checkbox Enabled. This is found on the Identity Inspector tab.

This can be done programmatically with the setIsAccessibilityElement and setAccessibilityLabel methods:

[self.myButton setIsAccessibilityElement:YES];
[self.myButton setAccessibilityLabel: @"label text for button"];
 

Use markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes

For mobile Safari-targeted content, do not use a WAI-ARIA widget with role="slider" because slider widgets are not currently accessible. Use the HTML5 range input type to enable accessible data input and validation.

<input type="range" ... />

Eclipse techniques

Eclipse applications must meet the required development techniques defined in Checkpoint 502.3.1 - Object Information and Checkpoint 502.3.4 - Values. Meeting these techniques is sufficient for meeting the requirements of this checkpoint (4.1.2).

Windows-based (MSAA+IA2) techniques

Windows-based (MSAA+IA2) applications must meet the required development techniques defined in Checkpoint 502.3.1 - Object Information and Checkpoint 502.3.4 - Values. Meeting these techniques is sufficient for meeting the requirements of this checkpoint (4.1.2).


Most links in this checklist reside outside ibm.com at the Web Content Accessibility Guidelines (WCAG) 2.0. W3C Recommendation 11 December 2008: http://www.w3.org/TR/WCAG20/

Copyright © 1994-2017 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University, Beihang University). All Rights Reserved.

Copyright © 2001, 2017 IBM Corporation