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

Assistive technologies should be able to understand the name, role and state of user interface elements.

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 HTML elements generally provide roles and properties by default. But custom-built ARIA elements will require those accessibility roles and properties to be set.

---

On this page:

• Requirements
• Why this matters
• Guidance for Design
• Guidance for Web
• More info

---

Requirements

• All interactive components have an ‘Accessible Name’;
• All interactive components communicate what type of component they are to assistive technologies;
• All interactive components communicate information about their state.

---

Why this matters

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 …

• the purpose of every interactive component (“button” or “tab” for example);
• how to identify it (“Submit” for example);
• what state it is in (“expanded” or “selected” for example).

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

• Annotating designs for accessibility by Henny Swan and The Paciello Group

---

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:

• In a ‘Submit’ button, the text ‘Submit’ provides the name of the button.
• The name of a button represented by a magnifying glass icon might be ‘Search’. In this example, the word ‘Search’ name might not be visible on the screen, but the button still needs a name. That name can be set in code (using aria-label for the Web 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

• Any <iframe> element used on the page should include a title attribute that accurately describes the frame content (e.g. “Travel form”).
  • This is important because some browsers and screen reader combinations won’t recognise the iframe content page’s <title> element as a source for the iframe’s ‘Accessible Name’ on your page.

Common mistakes

• An <a> or <button> element contains no text content, and so has no accessible name;
• A form field has no associated <label> element, and so has no accessible name;
• A <iframe> element used in the source code of the page doesn’t include a title attribute that accurately describes the frame content.

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

• Links, buttons and form fields should be implemented as native HTML controls (e.g. <a>, <button>, <input>, <select>), rather than as custom controls (e.g. using <div>, <span> elements and scripting that replicated the built-in behaviour of native HTML controls).

• When standard HTML controls do not exist (and only then), use generic HTML elements and provide equivalents via ARIA and via a method that does not require ARIA.

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:

• a button element has an implicit role of button;
• an a element with an href attribute has an implicit role of link;
• a li element has an implicit role of listitem;
• a dd element has an implicit role of definition;

• some HTML elements like div and span do not convey any role to assistive technologies.

  See the W3C ‘ARIA in HTML’ document to see the implicit roles of other HTML elements.

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:

• a link can be expressed with a a element with an href="..." attribute
• a button can be expressed with a button element or a input element with type="button"
• a group of radio buttons can be expressed with the fieldset, legend and input type="radio" elements

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

• HTML doesn’t have any ‘tab’ element. So if you want to create a tabbed user interface that screen reader users can understand, you’ll need to use the ARIA tablist, tab and tabpanel roles on top of ul, li, a and div or section elements.
• HTML has a dialog element, but it’s not well supported. So, as of November 2019, if you want to build a modal dialog, you should use a div and add role="dialog" as well as aria-modal="true. The button triggering the modal should have aria-haspopup="true".

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

• Using ARIA role without implementing the keyboard support that is implied that by role (see example further below);
• A <div> or <span> has been used as the basis for an interactive component, but ARIA role has not been used to identify the purpose of the component (or its constituent parts);
• A set of tabs is created using <ul>, <li>, and <a> elements, but the ARIA role attribute has not been used to provide the tablist, tab, and tabpanel roles;
• An <a> element has been used as the basis for a button, but the ARIA button role has not been applied.

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:

• Use aria-selected to express whether a li role="tab" element is the tab that is currently active within its ul role="tablist" parent.
• Use aria-expanded to express whether a component that opens and closes is currently expanded.
• Use aria-checked to express the state of switch component you’ve built with button role="switch"

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

• A button is used as the trigger to disclose content, but the aria-expanded attribute has not been used to communicate the disclosure component’s current state;

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:

• role="button" implies that this component is a button. Buttons can be activated using the ‘Enter’ and ‘Space’ keys. You will need to implement responses to these key presses yourself.

• div role="button" doesn’t automatically place that pseudo-button in the page’s tab order, which means that users couldn’t reach it using the Tab key. You’d need to remember to add that yourself too, by adding the tabindex="0" attribute.

  Note: it’s much better to use button or input type="button" as they come with keyboard support built-in.

More guidance for Web

W3C specifications and guidance documents

• Look at the W3C ARIA in HTML document to see:

  • what aria role is allowed on each HTML element;
  • what each aria role value means, and what aria- attributes you should/may use with it.

• Read the W3C Using ARIA document to know the “5 rules of ARIA” and understand a bit more about ARIA before creating custom components with ARIA.

• The ARIA 1.1 specification document has a lot of information about how to use each ARIA role and aria- attributes.

• The ARIA Authoring Practices Guide 1.1 is a great document that tells you how to implement a broad range of very common UI patterns (e.g. tabs, switches, toggles, dialog, feed, etc) with lots of details and working examples. It tells you:

  • What keyboard support you need to implement to meet users’ expectations (which are largely set by how the same patterns are implemented in operating systems)
  • How to build these components using ARIA. (But be careful to read the document’s ‘Read me first’ section if you intend to reuse these coding patterns as is)

Introduction articles

• What is an accessible name? and Understanding semantics by Léonie Watson and The Paciello Group
• Semantics to Screen Readers by Melanie Richards explains how screen readers, browsers and HTML work together

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

• Inclusive Components by Heydon Pickering provides good examples and tutorials
• Scott O’Hara’s Accessible Components are excellent and well documented
• Adrian Roselli’s blog provides lots of examples

About iframes specifically

• Creating Accessible Iframes by WebAIM

---

More info

Sources

• W3C Web Content Accessibility Guidelines 2.1
• Government Digital Service WCAG 2.1 Primer
• Barclays’ Accessibility Design Standards
• The BBC’s Mobile Accessibility Guidelines

Contribute

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

This site is open source. Improve this page.