Foundations: accessible names and descriptions

Posted on Wednesday, 5 April 2023 by Henny Swan

An element's name, or accessible name, is how it's identified. An accessible description provides additional information, about the element, that complements the accessible name.

In this post we explore assigning accessible names and descriptions using HTML and WAI-ARIA.

Why are accessible names important?

An accessible name is the information used by Assistive Technologies (AT) to identify an element such as an image, link, button, or form input. AT is software or hardware used by people with disabilities to help them do a number of things including navigating web content.

For example, people browsing with a desktop screen reader or browsing with a mobile screen reader rely on accessible names so they can understand content. Using a button as an example, if it has an accessible name of Search the screen reader will announce Search when it encounters it.

A visible search button with the Voiceover speech output b — When the Voiceover screen reader encounters a button with an accessible name of search, "Search" is announced as shown in the speech dialog box.

People browsing with speech input rely on accessible names, so they can interact with content using speech commands. Using the button example again, a person navigating using speech can say click Search to activate the search button.

HTML

Using HTML semantics, an accessible name can be created in a number of ways.

For links, the <a> element's content gives the link its accessible name of About us:

<a href="index.html">About us</a>

For images, an alt attribute gives an image an accessible name of TetraLogical Logo:

<img src="tetralogical_logo.png" alt="TetraLogical logo">

For form inputs, a <label> gives an input an accessible name of Terms and conditions when its for attribute has the same value as the id attribute on an <input>.

<input type="checkbox" id="terms">
<label for="terms">Terms and conditions</label>

For buttons, the <button> element's content gives a button an accessible name of Search:

<button>Search</button>

WAI-ARIA

WAI-ARIA (Web Accessibility Initiative Accessible Rich Internet Applications) complements HTML semantics by providing a set of attributes that allow you to enhance the native roles of HTML elements to build more accessible user experiences. You can read more about this in introduction to WAI-ARIA.

WAI-ARIA has two attributes that can provide, or alter, accessible names for elements: aria-label and aria-labelledby. Each have a slightly different use, but the thing to remember is that they will both override the native HTML accessible name.

Name

The aria-label attribute takes a piece of text as its value. This text becomes the element's label or accessible name. In the following example, the screen reader will announce Search button:

<button id="search" aria-label="Search"></button>

The aria-labelledby attribute uses text that exists elsewhere in the document as a label. It takes the value of the id attribute on the element it points to, so it becomes the label or accessible name for the element with aria-labelledby applied to it. In the following example, the screen reader will also announce Search button:

<h2 id="searchLabel">Search</h2>

<label for="search">Enter search term
  <input type="search" id="search">
</label>
<button aria-labelledby="searchLabel"></button>

Description

The aria-describedby attribute gives an element an accessible description. It also points to text elsewhere in the document taking its value from the id attribute on the element it points to. In the following example and demo, a screen reader will announce Password, minimum of 8 characters, with at least one number, and a mixture of uppercase & lowercase letters.

<label for="passwordLabel">Password</label> <input type="password" id="passwordLabel" name="password" aria-describedby="passwordDescription">
<p id="passwordDescription">Password, edit, protected, must be at least 20 characters and contain upper and lowercase letters, numbers and other characters</p>

Transcript:

An input field is reached with a screen reader. The field is preceded by the text label "Password", and is followed by the instruction "Must be at least 20 characters and contain upper and lowercase letters, numbers and other characters". Upon reaching the field, the screen reader reads out both the label and the instruction.

[Screen reader]: Password, edit, protected, must be at least 20 characters and contain upper and lowercase letters, numbers and other characters.

While an interactive element must have an accessible name, an accessible description is optional. Screen readers will announce the element’s role, state (if it’s important), and its accessible name, and then (after a brief pause) its accessible description (if one has been provided).

Tips

Always use semantic HTML over WAI-ARIA when it is available
Do not change native semantics, unless you really have to
Use the ARIA Authoring Practices Guide (APG) as a reference for how to apply role, name, description, state and keyboard behaviour for accessible custom components

Summary

An accessible name is the information used by Assistive Technologies to identify an element such as an image, link, button or form input
Interactive elements can be assigned an accessible name using HTML or WAI-ARIA aria-label or aria-labelledby
Elements can be given an additional description using aria-describedby
Interactive elements must have an accessible name, an accessible description is optional
aria-label and aria-labelledby will override the native HTML accessible name

Related WCAG 2.1 Success Criteria

Success Criterion 4.1.2 Name, Role, Value (Level A)

More information

For more information about the Web Content Accessibility Guidelines, read our WCAG primer. You can offer self-led training courses in Accessible web development and Accessible web QA.