accessibility-guidelines

This document is in beta. Help us by reporting issues via Github or email

Back to the overview page

Name, Role and State of interactive components

On this page:


Summary

The code should enable assistive technologies to understand the name, role and state of every interactive UI component.

Every user interface components that users can interact with should convey an ‘Accessible Name’, what type of component it is (for example “tab”, “switch” or “heading”), and its current state to assistive technologies.

Native elements (meaning elements that come out of the box in HTML, iOS and Android) generally provide roles/traits and properties by default. But custom-built elements will require all accessibility roles/traits and properties to be set.


Requirements

Why?

Users of assistive technology, such as screen readers, rely on accessibility properties such as role, name, value, and state to be set appropriately in order to know how to identify and interact with an element or object.

Following this guidelines ensures that screen readers and speech-input software understand …

Official wording in the Web Content Accessibility Guidelines

4.1.2 Name, Role, 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. (Level A)

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

See the W3C’s detailed explanation of this guideline with techniques and examples.


Guidance for Design

This section needs more content. Contribute via Github or email.

More guidance for design


Guidance for iOS

This section needs more content. Contribute via Github or email.


Guidance for Android

This section needs more content. Contribute via Github or email.


Guidance for Flutter

Flutter deals with assistive technologies like screen readers using the Semantics() widget. For a quick introduction of the Semantics() widget you can read this article.

##

If a widget does not have a ‘Accessible Name’ by default then use Semantics().

The Semantics() widget has many properties for adding semantics that can be read by a screen reader but for a custom one use label as shown below.

Semantics(
    lable: String, // lable for a custom semantic name
    child: // widget in need of semantics
)

Guidance for Web

Requirement 1: Ensuring that UI components have an accessible name

Every user interface components that users can interact with needs to have a name that assistive technologies (like screen readers or speech-input software) can understand.

That name is called the ‘Accessible Name’. (In the official Web Content Accessibility Guidelines, that name is just called ‘name’).

For example:

Where does the ‘Accessible Name’ of a UI components come from?

An interactive UI component might be given an Accessibility Name in a number of ways:

  1. from its content (like in the ‘Submit’ button example above);
  2. from a visible label it is associated with in code (in HTML this might be by associating an input element with a label element, or by using aria-labelledby);
  3. from a property set in code (like aria-label="Search").

For <iframe> elements

Common mistakes

Requirement 2: Ensuring that Assistive Technologies can understand what type of component a UI component is

Coding of user interface components using native HTML controls

ARIA Use case 1: If you need to fix HTML that has the wrong (or missing) semantics

Most HTML elements have an implied ‘role’, that communicate what type of component it is to Assistive Technologies. For example:

If incorrect HTML element was used to build a component, or if a div or span has been used where something more meaningful like a button or a href="..." should have been used, you can do two things:

  1. In almost every case, the best response is to fix the HTML if you can, so it conveyes the right semantics, rather than using ARIA. See the First rule of ARIA in the W3C Using ARIA document.
  2. If you really can’t fix the HTML itself, you might be able to fix the element’s semantics using ARIA. Please only do this if you know what you’re doing with ARIA and if you’re also testing the result yourself with a screen reader.
ARIA use case 2: If you need to build an interactive component that HTML semantics can’t express

Many common interactive components can be expressed with HTML alone. For example:

But other very common interactive elements can’t be semantically expressed with HTML alone. For example:

The HTML code of custom controls (e.g. sliders, tabs, accordions) should the right ARIA attributes to describe their role and status (e.g. tab, slider, selected, expanded, collapsed).

Common mistakes

Example

<!-- Example 1 - standard control -->
<input type="checkbox" id="c1" /><label for="c1">Remember me</label>

<!-- Example 2 - ARIA supported tree view with fall-back -->
<ul role="tree">
  <li aria-level="0" aria-expanded="true" role="treeitem">
    <a href="...">TV Shows <span class="offscrn"> - Expanded</span></a>
    <ul>
      <li aria-level="1" role="treeitem"><a href="...">Comedy</a></li>
      <li aria-level="1" role="treeitem"><a href="...">Drama</a></li>
      <li aria-level="1" role="treeitem"><a href="...">Sports</a></li>
    </ul>
  </li>
  <li aria-level="0" aria-expanded="true" role="treeitem">
    <a href="...">Radio Shows <span class="offscrn"> - Expanded</span></a>
    <ul>
      <li aria-level="1" role="treeitem"><a href="...">News</a></li>
      <li aria-level="1" role="treeitem"><a href="...">Soap</a></li>
      <li aria-level="1" role="treeitem"><a href="...">Sports</a></li>
    </ul>
  </li>
</ul>
Failure example
<!-- Don't do this -->

<!-- Example 1 - non-standard control -->
<div><img src="chkbx" alt="checkbox" />Remember me</div>

<!-- Example 2 - inaccessible tree view -->
<div>
  <div onClick="toggle();">
    TV Shows
    <div>
      <div class="indent">Comedy</div>
      <div class="indent">Drama</div>
      <div class="indent">Sports</div>
    </div>
  </div>
  <div onclick="toggle();">
    Radio Shows
    <div>
      <div class="indent">News</div>
      <div class="indent">Soap</div>
      <div class="indent">Sports</div>
    </div>
  </div>
</div>

Requirement 3: Ensuring that Assistive Technologies can understand what state a UI component is in

If you ARIA’s role property to create components that HTML alone can’t express, you will often need to use aria- attributes to express the properties and states of those components. For example:

The HTML code of custom controls (e.g. sliders, tabs, accordions) should the right ARIA attributes to describe their role and status (e.g. tab, slider, selected, expanded, collapsed).

Common mistakes

Remember: an ARIA role is just a promise. You need to implement the keyboard support yourself

The role and aria- only tell Assistive Technologies how to announce a component to screen reader users. The keyboard interactions that are implied by different ARIA roles are still for you to implement.

For example, let’s imagine that you’re building a button using div role="button", rather than using the native HTML button or input type="button" elements:

More guidance for Web

W3C specifications and guidance documents

Introduction articles

High-quality accessible component patterns using ARIA that’s fully supported today

About iframes specifically


More info

Sources

Contribute

This document is in beta. Help us by reporting issues via Github or email