When it comes to creating accessible products, understanding the interactions between different technologies and the code we write is very helpful. In this post, Joe Watkins talks about accessible name–what it is, how to apply it, and why it’s such an integral tool in the accessibility toolkit.

I remember the day, digging around the W3C’s documentation, I stumbled upon the definition of the Accessibility API. After jumping into the Accessibility API rabbit hole, it occurred to me that there is a huge world of behind-the-scenes technology supporting a dance between browsers and assistive technology. This journey led me to Accessible Name.

It’s important to write clean, standards-based code, as we know. Once I learned about accessible name, however, I realized the importance of having a high-level understanding of the interactions between different technologies and the code we write. This helps bridge the gap between the how and the why.

Accessible name is the name of a user interface element. Its value is a big part of what is communicated to users of assistive technology. Without it, people who rely on those technologies would have difficulty understanding or interacting with much of the content on the page. Once I understood what accessible name was, and its critical role in web accessibility, I was on my way to creating more accessible experiences.

In this article, I’ll explain accessible name and how assistive technologies interact with web browsers. Together, we’ll explore some code examples. Finally, I’ll show you a cool new accessibility browser tool so you can test for accessible name and feel confident that the code you write is more accessible than ever!

Assistive technology is separate technology

Before we talk about accessible name, we should first understand that assistive technology, like a screen reader, is a separate application that works along with a web browser. VoiceOver is not part of Safari, JAWS is not part of IE, and NVDA is not part of Firefox.

Because screen readers are separate applications and not built into web browsers, they need a mechanism for getting the content from the web browser to the person using them. Let’s explore how assistive technology (AT) is able to interface with the web browser, using a screen reader as one of the most common types of AT that people use.

Graphical representation of a web browser and a screen reader but nothing connecting them programmatically. The disconnection is represented with a question mark and arrows pointing in each direction.

The accessibility API

You may be familiar with the concept of an API or Application Programming Interface. Let’s say we were developing a website and we wanted to get the last 20 tweets from a particular Twitter user. There needs to be an interface between our website and Twitter to establish a connection and pass along the data we want to use. That is the API–without it, we wouldn’t be able to connect to Twitter and get the data we want.

The screen reader has access to what is called the Accessibility API. It is very similar to the DOM API. The operating system exposes objects and events to assistive technology through this API. This is the connector we need to get the information from the web browser to the screen reader. Well, we don’t need it — it all happens automatically — we just need to understand the basic mechanics.

The screen reader can also communicate user interactions and commands back to the web browser to interpret using the accessibility API.

Graphical representation of a web browser communicating with the accessibility API which is being interacted with by a screen reader. This communication between web browser, accessibility API, and screen reader is depicted with arrows going back and forth.

The accessibility tree

The web browser converts the DOM into what is called the Accessibility Tree which is a tree of objects that represent the structure of the user interface. If you were 10 years old again and climbed this tree, you’d find many nested branches with leaves, or nodes, which represent  HTML elements, e.g. button, input field, or div.

This tree is what is exposed to assistive technology via the accessibility API.

Screenshot of the Accessibility inspection features for Chrome Developer Tools enabled and open inspecting the document. From the Elements tab the Accessibility sub-tab is chosen, and a representation of the accessibility tree is pointed to and highlighted.

The image above is a screenshot of the Accessibility inspection features for Chrome Developer Tools enabled with the accessibility tab selected. When you inspect an element you are given a bird’s eye view of the accessibility tree.

To enable this feature/experiment in Chrome, watch this screencast video below or follow these steps:

  1. Using Chrome, open the Chrome Flags by visiting this url: chrome://flags
  2. Search for “Developer Tools experiments” and enable those.
  3. Use Ctrl+Shift+I (or Cmd+Opt+I on Mac) to open the DevTools.
  4. Go to Settings -> Experiments -> check Accessibility Inspection
  5. Close DevTools and reopen.
  6. Select Elements and inspect an element.
  7. You can find the Accessibility tab in the same row as Styles, Computed, Event Listeners.

Video description: Screencast video, with no sound, demonstrating how to enable the accessibility inspection features for Chrome Developer Tools experiment.

Accessible name

Many elements in the accessibility tree need a name so they are clearly communicated to assistive technology. That name is the accessible name. The accessible name is part of what is announced by a screen reader when that element receives focus. The value of the accessible name can be both visual content or hidden text alternatives. Not every single element in the DOM needs an accessible name. For example, non-semantic elements used for style or presentation only such as  <div> or <span> do not need an accessible name defined.

The examples below were tested using the VoiceOver screen reader with Safari.


Not good:

<button type=”submit”></button>
  • The accessible name for this button is: “”
  • VoiceOver announces: “button”
  • Why? There is no text inside the <button> element.

Good:

<button type=”submit”>Update Details</button>
  • The accessible name for this button is: “Update Details”
  • VoiceOver announces: “Update Details, button”
  • Why? The text inside the element is the accessible name.

Not good:

<input type="submit">
  • The accessible name for this button is: “submit”
  • VoiceOver announces: “submit, button”
  • Why? There is no value attribute defining the action or accessible name. “Submit” may not be a suitable action for the input in all cases. Some AT may inaccurately try to guess what the accessible name is if one isn’t defined. Browser default values for these inputs, without value attributes defined, may not be consistent.

Good:

<input type="submit" value="Update Details">
  • The accessible name for the input element is: Update Details
  • VoiceOver announces: “Update details, button”
  • Why? The accessible name is delivered via the value attribute.

Not good:

<img src=”34422_some-file_2bsca.jpg”>
  • The accessible name for the image is: “”
  • VoiceOver announces: “Thirty four thousand four hundred and twenty two some file two bcsa jpg, image”
  • Why? The img tag is missing an alt attribute so the screen reader announces file name.

Good:

<img src=”file.jpg” alt="Woman holding a baby">
  • The accessible name for the image is: “Woman holding a baby”
  • VoiceOver announces: “Woman holding a baby, image”
  • Why? The img tag has an alt attribute with a descriptive value.

Not good:

<div>Search</div>
<input id=”search” type=”text”> 
  • The accessible name for the input field is: “”
  • VoiceOver announces: “edit text”
  • Why? The input field is missing an associated <label>

Good:

<label for=”search”>Search</label>
<input id=”search” type=”text”>
  • The accessible name for the input field is: “Search”
  • VoiceOver announces: “Search, edit text”
  • Why? The <label> is programmatically associated with the input field when the for attribute matches the value of the id.

Not good:

<div class=”hamburger-menu”>
  <span class=”line”></span>
  <span class=”line”></span>
  <span class=”line”></span>
</div>

Good:

<a href=”#hamburger-menu” class=”hamburger-menu”>
  <span class=”visually-hidden”>Menu</span>
  <span class=”line” aria-hidden=”true”></span>
  <span class=”line” aria-hidden=”true”></span>
  <span class=”line” aria-hidden=”true”></span>
</a>
  • The accessible name for the hamburger menu trigger is: “Menu”
  • VoiceOver announces: “Menu, link”
  • Why? The link is focusable by a keyboard and assistive technology as well as having visually hidden text content.

Good:

<h1>We're building a digital world for everyone</h1>
  • The accessible name for the heading is: “We’re building a digital world for everyone”
  • VoiceOver announces: “We’re building a digital world for everyone, heading level one”
  • Why? The element has visual text content.

Good:

<some-custom-element aria-label=”I am a custom critter” tabindex=”0” role=”button”>...</some-custom-element>
  • The accessible name for the custom element is: I am a custom critter
  • VoiceOver announces: “I am a custom critter, button”
  • Why? The custom element is focusable because of tabindex=”0” and has been given an accessible name with aria-label=”…”

P.S. Just use a <button> 🙂


In the examples above, we can hear the screen reader announce the accessible name. In addition to announcing the accessible name, the screen reader announces the role of the element, e.g. button, image, edit text, heading.

Other methods of adding an accessible name to an element are using attributes like aria-labelledby, aria-label, and even the title attribute (Use title with caution).

Test for accessible name

To test for accessible name you can use a screen reader and listen to how that element is announced.

In the video below, we send focus to an input field that does not have an accessible name defined and “edit text, blank” is announced by the screen reader. A non-sighted screen reader user would not understand what that form field is for.

From the code, we programmatically tie the label to the input field with the for attribute and the accessible name is then announced by the screen reader when the input field receives focus, e.g. “First Name, edit text”

Another way to test for accessible name is using the accessibility inspection features we installed earlier in this post. In the video below, we open the Chrome DevTools and choose the elements tab. We then choose the accessibility tab over by the styles tab. From there, we can see the name property that shows what will be announced by a screen reader.

The importance of accessible name

By including a meaningful accessible name in everything you create, you are well on your way to making sure these elements will be communicated clearly to screen reader users and made available to other assistive technologies like voice recognition software. Form fields will have labels, buttons will have text, images will have text alternatives, and this old world will be a little more inclusive!

Now that you have an understanding of why accessible name is important to consider when developing, get out there and test your own creations for it. Feel free to ping us in the comments if you have any questions or thoughts.

2 thoughts on “Demystifying accessible name”

Read comments

  1. Birkir Gunnarsson says:

    Great article! The only code example I would change is the input type=”submit” button, the accessible version of it is input type=”submit” value=”accessible name”. The current example (using a button element) is perfectly correct, but maybe you can add this one, to show that input type=”submit” can be given an accessible name through the value attribute. When I explain this to developers I often get asked why some screen readers (primarily Jaws) announce accessible names even if one is not assigned in the API. I explain that they use heuristics to guess it, but they shouldn’t have to and besides they sometimes get it wrong (and having the wrong accessible name for an operable element can lead to trouble for the user).

  2. Joe Watkins says:

    Birkir, thank you for a great suggestion 🙂 I’ve added that to the post. AT guessing accessible name might be a great topic for a follow-up article!

    Thanks for reading and contributing!

Hi there! We've closed the comments after a week of spirited discussion on this post. If there's something we've missed, please reach out and let us know.