Web checklist

Checkpoint 4.1b: Name, Role, and Value

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.


Rationale

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

When developers use standard controls from accessible technologies and they develop the user interface elements according to specification, the application will meet compliance.

Custom widgets (link resides outside of ibm.com) that are not included in the (X)HTML host language, yet found in many Web applications, 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. When this information is not conveyed to assistive technologies, widgets created through the use of CSS and JavaScript® are difficult, if not impossible, to identify and operate. Common examples are menus, trees, data grids, accordions, and dialog boxes. Embedding WAI-ARIA markup and implementing arrow key navigation in Web widgets enables people with disabilities to identify and interact with the widgets in the same manner they identify and interact with desktop application widgets.

Before implementing a custom widget, follow these recommendations:

  1. Locate an example widget at OpenAjax WAI-ARIA examples (link resides outside of ibm.com) that is similar to the widget you are developing.
  2. Examine how a screen reader identifies the widget's name, role, and value through the WAI-ARIA attributes that the widget uses.
  3. Examine how the widget's keyboard navigation operates, specifically:
  4. Consult the WAI-ARIA Authoring Practices and WAI-ARIA technical specification (both links reside outside of ibm.com) to verify that your implementation meets best practices and specification requirements.

Required development and unit test techniques


To comply with this checkpoint, you must meet at least one of the following techniques. These techniques are defined in WCAG 2.0 Level A Success Criterion 4.1.2 (link resides outside of ibm.com).

  1. Markup to expose name and role: Use markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes.
  2. Accessibility API to expose name and role: Use 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.
  3. 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.
  4. Allow user-settable properties: Expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes.
 

Note: Maintaining the user's point of regard is required to meet this checkpoint.
The point of regard is a position in rendered content that has focus.  Exiting a dialog  or dynamically refreshing a page (or part of a page) using AJax or equivalent are two examples where  the user's point of regard has to be maintained.

Note: The examples presented in the techniques are not exhaustive. They are meant to illustrate the spirit of this checkpoint.

At this time WAI-ARIA examples are only fully supported in Firefox version 3.6 or later and version JAWS 12 or later. If your product needs to be accessible in Internet Explorer and mobile Safari/VoiceOver, one or more of the required HTML/CSS specific techniques must be implemented, as well as a WAI-ARIA technique. When WAI-ARIA becomes an approved W3C recommendation and Internet Explorer and mobile Safari/VoiceOver fully support it, then WAI-ARIA techniques alone will be sufficient to comply with this checkpoint.

Applications that provide WAI-ARIA must add the following statement to the checkpoint comments column of the Web Accessibility Checklist:

Note: This product uses WAI-ARIA to comply with this checkpoint. WAI-ARIA is supported on Windows using Firefox version 3.6 or later and JAWS version 12 or later, and supported on iOS v5.0 and later using Safari and VoiceOver.

General examples

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

    To comply with this technique, you must implement all of the WCAG 2.0 examples for using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes (link resides outside of ibm.com).

    General example 1

    For additional information, refer to the WCAG 2.0 examples of using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes.

  2. Accessibility API to expose name and role: Use 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.

    To comply with this technique, you must implement the following example.

    General example 2

    If you are using a standard user interface component in a programming technology, you must implement all of the WCAG 2.0 examples for using the accessibility API features of a technology to expose names and roles, allow user-settable properties to be directly set, and provide notification of changes (link resides outside of ibm.com).

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

    To comply with this technique, you must implement the following example.

    General example 3

    To create your own user interface component in a programming language that supports accessibility API, refer to the WCAG 2.0 examples of 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 (link resides outside of ibm.com).

  4. Allow user-settable properties: Expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes.

    There are no general examples of how to implement this technique.

    Required unit tests for all general development techniques

    Refer to the required unit tests for all development techniques below.


HTML examples

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

    To comply with this technique, you must implement at least one of the following examples. in 1 through 6 or 10 through 11. For mobile Safari targeted content, examples 7, 8 and 9 must be implemented in addition to one of the examples in 1 through 6 or 10 through 11.

    HTML example 1

    HTML form controls and links are accessible, as long as the developer follows the HTML examples throughout the checkpoints in this checklist. When possible, developers should use standard HTML form controls and links.

    HTML example 2

    Use label elements to associate text labels with form controls. This requirement is satisfied by completing technique #1 in Checkpoint 1.3d: Forms.

    HTML example 3

    Using the title attribute of the frame and iframe elements. This requirement is satisfied by completing technique #2 in Checkpoint 2.4c: Frames.

    HTML example 4

    Use the title attribute to identify form controls when the label element cannot be used. To meet this requirement, complete technique #1 in Checkpoint 1.3d: Forms.

    HTML example 5

    To verify that your pages fully conform to specifications, you should run your code through an automated validator and ensure that all HTML specification errors are corrected.

    For additional information, refer to the WCAG 2.0 examples for using HTML according to spec.

    HTML example 6

    Until recently, screen readers generally had trouble reading dynamic Web content that changes frequently, such as stock ticker quotes or news feeds. As a result, dynamic content was often completely inaccessible to screen reader users. With the advent of WAI-ARIA live regions, Web application developers can easily make dynamic content accessible to screen reader users.

    See the live region example in checkpoint 2.2b and Implementing Live Regions in the WAI-ARIA Authoing Practices.

    HTML example 7

    The Dojo mobile DatePicker widget is not accessible at this time. Therefore, when a date picker is required for mobile Safari targeted content, use the accessible HTML5 date picker or datetime picker elements.

    Date picker syntax:

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

    When a date field receives focus, mobile Safari displays the following picker control:

    Dojo mobile DatePicker widget

    Date picker syntax:

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

    When a datetime field receives focus, mobile Safari displays the following picker control:

    Dojo mobile DatePicker widget with time

    HTML example 8

    The Dojo mobile TimePicker widget is not accessible at this time. Therefore, when a time picker is required for mobile Safari targeted content, use the accessible HTML5 time picker element or the datetime element documented in the previous example.

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

    When a time field receives focus, mobile Safari displays the following picker control:

    Dojo mobile TimePicker widget

    HTML example 9 (for iOS platform)

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

    <input type="range" ... />
    Dojo mobile widget displaying a slider

    Required unit tests for HTML development technique 1

    Refer to the required unit tests for all development techniques below.

  2. Accessibility API to expose name and role: Use 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.

    To comply with this technique, you must implement the following example.

    HTML example 10

    Use WAI-ARIA to programmatically assign role and state to custom widgets.

    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" 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 above 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.

    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.

    HTML example 11

    To help users navigate a page, WAI-ARIA widgets must have an accessible name specified with aria-label, aria-labelledby or the widget's inner text.

    The following example shows a tree labelled 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 which 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 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
slider aria-label, aria-labelledby
spinbutton 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
toolbar aria-label, aria-labelledby

Required unit tests for HTML development technique

Refer to the required unit tests for all development techniques below.

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

    There are no examples for implementing this technique in HTML.

  2. Allow user-settable properties: Expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes.

    There are no examples for implementing this technique in HTML.


Script examples

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

    To comply with this technique, you must implement all of the following examples.

    Script example 1

    Use functions of the Document Object Model (DOM) to add content to a page.

    If you are using script or code to re-purpose a standard user interface component in a markup language, refer to the WCAG 2.0 examples of using functions of the DOM to add content to a page (link resides outside of ibm.com).

    Required unit tests for Script development technique 1

    Refer to the required unit tests for all development techniques below.

  2. Accessibility API to expose name and role: Use 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.

    There are no examples of implementing this technique with scripts.

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

    There are no examples of implementing this technique with scripts.

  4. Allow user-settable properties: Expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes.

    To comply with this technique, you must implement at least one of the following examples.

    Script example 2

    Use functions of the Document Object Model (DOM).

    To use script or code to re-purpose a standard user interface component in a markup language, refer to the WCAG 2.0 examples of using functions of the DOM to add content to a page (link resides outside of ibm.com) when implementing this technique.

    Script example 3

    Custom dialog widgets developed with CSS and JavaScript 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 application, dialog and header 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.

    You can view the source code for this example in the browser view source function or Firebug®.

    Activate the button to render a dialog box.

    Note for iOS platform: Mobile Safari/VoiceOver does not currently support the WAI-ARIA dialog and alertdialog roles. Therefore, VoiceOver does not announce dialogs when they are rendered. Additionally, the Dojo mobile dialog widget is not accessible because it does not contain the required WAI-ARIA dialog markup to make it accessible.

    If teams choose to use the Dojo mobile dialog widget without the required WAI-ARIA dialog markup, this checklist checkpoint must be answered “no” and a deviation must be filed.

    After the Dojo team implements the proper WAI-ARIA markup in the mobile dialog widget, teams may answer this checkpoint with a “yes” and are not required to file a deviation. Teams may want to follow the status of the Dojo mobile defect that addresses this issue. You may have to register as a member of the IBM Dojo Toolkit community at csnext in order to see the defect.

    Note that when the proper WAI-ARIA markup is added to the Dojo mobile dialog widget, VoiceOver will still not announce a dialog until Apple implements a fix for WAI-ARIA based dialogs. However, after the Dojo team implements WAI-ARIA in the dialog widget, IBM will have fulfilled its responsibility to provide an accessible widget.

    Script example 4

    The first two tables below contain required child and parent roles for specific WAI-ARIA widgets. The last table contains required properties for specific 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 WAI-ARIA roles that require child elements:


    Role Required child
    combobox listbox or textbox
    grid row
    list listitem
    listbox option
    menu menuitem or menuitemcheckbox or menuitemradio
    radiogroup radio
    row gridcell
    tablist tab
    tree treeitem
    treegrid row

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


    Role Required parent container
    columnheader row
    gridcell row
    listitem list
    menuitem menu or menubar
    menuitemcheckbox menu or menubar
    menuitemradio menu or menubar
    option listbox
    row grid or treegrid
    rowgroup grid
    rowheader row
    tab tablist
    treeitem tree

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


    Role Required property
    alertdialog aria-labelledby or aria-label
    checkbox aria-checked
    dialog aria-labelledby or aria-label
    form aria-labelledby or aria-label
    menuitemcheckbox aria-checked
    menuitemradio aria-checked
    progressbar aria-valuenow and aria-valuemax and aria-valuemin
    radio aria-checked
    radiogroup aria-labelledby or aria-label
    region aria-labelledby or aria-label
    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

    Required unit tests for all development techniques

    Manually perform the following unit tests.


Recommended development techniques

Although you do not have to implement the recommended techniques in order to comply with this checkpoint, you should review them because they can improve the accessibility and usability of the application.

Refer to WCAG 2.0 Additional Techniques (Advisory) for Success Criterion 4.1.2 (link resides outside of ibm.com)


©2013 IBM Corporation

Last updated January 1, 2013.

W3C Recommendation 11 December 2008: http://www.w3.org/TR/WCAG20/ (link resides outside of ibm.com)
Consortium for Informatics and Mathematics, Keio University), All Rights Reserved.