Exposing basic information about UI elements (HTML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Looking for the C#/VB/C++/XAML version of this topic? See Exposing basic information about UI elements (XAML).

Assistive technologies such as screen readers need information about the UI elements in an app. The system provides the information based on an app's HTML markup. We'll describe the HTML that you need to implement to ensure that your app exposes the basic information that assistive technologies need.

Accessible name

An accessible name is a short, descriptive text string that a screen reader uses to announce a UI element. You should set the accessible name for UI elements that have a meaning that is important for understanding the content or interacting with the UI. Such elements typically include images, input fields, buttons, controls, regions, and so on.

The following table describes how to define an accessible name for various types of HTML elements.

Element type	Description
Static text	For text and other HTML tags, the accessible name is based on the visible (inner) text. Examples include the p and h1 tags.
Images	For images, the alt attribute is used as the accessible name. This applies to images that you specify with the img tag, image buttons that you specify with <input type="image">, and area tags that you use with image maps. For more information about image maps, see Image maps in the World Wide Web Consortium (W3C) HTML5 specification.
Form fields	The accessible name for a form field such as <input type="text| password| checkbox| radio|...">, or for a select or textarea tag, should be the same as the label that is displayed for the field. The preferred way to associate a label with an input field is to use the label tag and set the for attribute. When the user clicks the label tag, the focus moves to the associated control. For more information about labeling UI elements, see Labeling and Describing in Web Accessibility Initiative - Accessible Rich Internet Applications (WAI-ARIA) 1.0 Authoring Practices.
Buttons and links	By default, the accessible name of a button or link is based on the visible text. For a and button tags, the accessible name is based on the inner text of the tag. For an input tag of type="button", the accessible name is based on the value attribute.
Tables	The accessible name of a table is typically defined with a caption tag in the table.
Structure and landmark elements	Giving labels to structure and landmark elements is important because screen readers use the labels to navigate a document. Elements that need labels include forms, frames, regions, and other elements with landmark roles such as "main", "navigation", and "search".
Elements in a div	For all elements that are typically defined by using a div tag, including custom elements, you can set an accessible name by using one of the following attributes: aria-labelledby—to refer to the element that contains the text to use as the accessible name. aria-label—to set the accessible name directly. title—to create a tooltip that is also used as the accessible name. You should use the previous attributes with custom UI elements (for example, with div tags), and when you want to override the default HTML attributes.

 

This example shows how to define an accessible name for various types of HTML elements.

<!--Label landmark regions by using aria-labelledby or aria-label. -->      
<h1 id="formLabel">Personal Information</h1>
<form aria-labelledby="formLabel" ... > 

    <!-- The label tag with "for" attribute sets the name of the input field. -->
    <label for="fullname">Full Name</label>
    <input id="fullname" type="text" accesskey="N"/>

    <!-- Alt text is used as the image accessible name. -->      
    <img src="..." alt="Personal Photo" />

    <!-- An image button's accessible name is set with the alt attribute. -->
    <input type="image" src="images/back.png" alt="Back" onclick="..." />

    <!-- Inner text is used as the accessible name for A, BUTTON, P, and so on. -->
    <a href="...">More Photos</a> 

    <!-- The submit button uses default caption text as the accessible name. -->
    <input type="submit" /> 

</form>

For Windows Runtime controls, you can use data binding to set the accessible name.

<!-- Data binding maps the image alt attribute to the data source title field -->
<div class="..." data-win-control="Win.Binding.Template">
    <div class="image" data-win-bind="...; alt: title"></div>
    <div class="text">
        <h1 class="title" data-win-bind="textContent: title"></h1>
        <p class="description" data-win-bind="textContent: description"></p>
    </div>
</div>

<!-- List view can set the accessible name with aria-labelledby or aria-label. -->
<h1 id="pageTitle">Items collection page</ h1>
<div data-win-control="Win.UI.ListView" data-win-options="{...}" 
    aria-labelledby="pageTitle">
</div>

Note  The Microsoft UI Automation accessibility platform generates the UI tree representation of apps for UI Automation client usages. It represents the structure of the UI elements that are available for assistive technologies to inspect and interact with. You aren't specifying UI Automation info yourself. But you're relying on the built-in support from the Windows Runtime host that converts all the attribution that's relevant for HTML content into equivalent UI Automation info that creates a common accessibility or automation representation of each app being viewed.

 

Value

If a UI element has an associated value that is important for understanding the condition of the UI element, you need to expose this information to accessibility frameworks.

For example, an HTML control that is hosted in a div tag that has its role attribute set to "slider", "progressbar", or "spinbutton", must expose the aria-valuemax, aria-valuemin, and aria-valuenow attributes. In addition, your app must dynamically maintain the aria-valuenow attribute to reflect the changes in the element. A good practice is to set the aria-valuetext attribute to provide the text string that corresponds to the current value of the aria-valuenow attribute.

<div id="sl" role="slider" ... 
    aria-valuemin="1" aria-valuemax="5" aria-valuenow="3" aria-valuetext="good"...>
</div>

<script>
    function manageValue()
    {
        ...
        // Dynamically maintain aria properties for the current value and text.
        sl.setAttribute("aria-valuenow", currentValue);
        sl.setAttribute("aria-valuetext", currentValueText);
        ...
    }
}
</script>

State

Sometimes it is important to set and maintain the accessible state of a UI element (for example, by using the aria-disabled attribute). Setting and maintaining the accessibility state is particularly important for custom UI elements. The system has built-in support for maintaining the accessible state for all standard UI elements and Windows controls.

<!-- Declaring accessibility attributes for a custom image button. -->
<div id="folders" role="tree" aria-label="Folders">
...
</div>

<script>
    var folders = document.getElementById('folders');
    // Ensure keyboard navigation/operation with arrow keys
    folders.addEventListener('keydown', function(e) {
        var itm = e.srcElement;
        if ( e.keyCode === Win.Utilities.Key.leftArrow) {
            // The node is collapsed if it has children
            e.srcElement.setAttribute('aria-expanded', false );
        } else if ( e.keyCode === Win.Utilities.Key.rightArrow) {
            // The node is expanded if it has children
            e.srcElement.setAttribute('aria-expanded', true );
        }
    });
</script>

Note  To remove an element and all if its content from the UI Automation tree, use the aria-hidden attribute with the value set to true.

 

Role

You should assign a valid (non-abstract) WAI-ARIA role to custom UI elements. This gives screen readers more information about which behavior and properties to expect from UI elements.

It is also important to set the role for elements that are referenced by the aria-labelledby attribute and for elements that expose UI items that are important for user interaction.

In the following example, elements of a tree view are marked with the corresponding WAI-ARIA roles to enable screen readers to understand the structure of the tree view, and to expose its expand–collapse behavior.

<!-- Custom tree view element. -->
<div id="folders" role="tree" aria-label="Folders" tabindex="0" 
        aria-activedescendant="n-0" >
    <div id="n-0" role="treeitem" aria-expanded="true" onclick="..." >Libraries</div>
    <div role="group" >
        <div id="n-0-1" role="treeitem" aria-expanded="false" onclick="...">Docs</div>
        <div id="n-0-2" role="treeitem" aria-expanded="false" onclick="...">Music</div>
        <div id="n-0-3" role="treeitem" aria-expanded="false" onclick="...">Pics</div>
    </div>
</div>

To better illustrate accessibility concepts, the tree view in the previous example was simplified to include just a single element for each tree view node. In an actual implementation, expandable nodes would include two subelements, one to represent the expand–collapse functionality, and another to expose node activation functionality (for example, loading a list of contained files and folders).

<!-- An example of the expandable and actionable node. -->
...
    <div role="presentation">
    <img src="images/expand.png" role="presentation" onclick="expColl(event)"/>
    <span id="n-0" role="treeitem" onclick="activateItem(event)"
        aria-expanded="true" >Libraries</span>
    </div>
...

In the previous example, role="presentation" removes elements that have no semantic value from the UI tree (or accessibility tree). Note that role="presentation" removes the current element from the UI tree but does not affect the contained subelements. To remove the UI element and all of its child elements from the UI tree, use aria-hidden="true".

Some HTML5 tags, such as a or img, have strong implicit roles that cannot be overwritten except with the "presentation" role.

Accessible description (optional)

An accessible description provides additional accessibility information about a particular UI element. You typically provide an accessible description when an accessible name alone does not adequately convey an element's purpose.

The Narrator screen reader reads an element's accessible description only when the user requests more information about the element by pressing Caps Lock + F.

The best way to provide an accessible description is to use the aria-describedby attribute. This attribute refers to one or more other UI elements whose text content the system will use as the accessible description. Alternatively, you can provide the accessible description by implementing a tooltip that includes the title attribute. For more info, see Making tooltips accessible.

<!-- Declaring visible text as the accessible description of a table. -->
<p id="tableDesc">This table describes travel expenses organized by destination and dates.</p>
<table aria-describedby="tableDesc">...<table>

Related topics

Meeting basic accessibility requirements