ARIA items do not have accessible names
Users of screen readers and other assistive technologies need information about the behavior and purpose of controls on your web page. Built-in HTML controls like buttons and radio groups come with that information built in. For custom controls you create, however, you must provide the information with ARIA roles and attributes. (Learn more in the Introduction to ARIA.)
To be announced properly by assistive technologies, both built-in HTML controls and custom ARIA controls must have accessible names that convey their purpose.
How Lighthouse identifies ARIA items without accessible names
Lighthouse flags custom ARIA items whose names aren't accessible to assistive technologies:

There are 7 audits that check for accessible names, each one covers a different set of ARIA roles. Elements that have any of the following ARIA roles but don't have accessible names will cause this audit to fail:
Audit name | ARIA roles |
---|---|
aria-command-name | button , link , menuitem |
aria-input-field-name | combobox , listbox , searchbox , slider , spinbutton , textbox |
aria-meter-name | meter |
aria-progressbar-name | progressbar |
aria-toggle-field-name | checkbox , menu , menuitemcheckbox , menuitemradio , radio , radiogroup , switch |
aria-tooltip-name | tooltip |
aria-treeitem-name | treeitem |
Caution: Most common input types can be created with standardized HTML elements, which come with built-in behaviors and accessible semantics that can be time consuming to replicate. Consider using built-in elements instead of ARIA roles if possible.
The Lighthouse Accessibility score is a weighted average of all the accessibility audits. See the Lighthouse accessibility scoring post for more information.
Example 1: How to add accessible names to your custom ARIA toggle fields
Option 1: Add inner text to the element
The easiest way to provide an accessible name for most elements is to include text content inside the element.
For example, this custom checkbox will be announced as "Newspaper" to assistive technology users:
<div id="checkbox1" role="checkbox">Newspaper</div>
Using the clip pattern you can hide the inner text on screen, but still have it announced by assistive technology. This can be especially handy if you translate your pages for localization.
<a href="https://web.dev/accessible">Learn more <span class="visually-hidden">about accessibility on web.dev</span></a>
Option 2: Add an aria-label
attribute to the element
If you can't add inner text—for example, if you don't want the element's name to be visible—use the aria-label
attribute.
This custom switch will be announced as "Toggle blue light" to assistive technology users:
<div id="switch1"
role="switch"
aria-checked="true"
aria-label="Toggle blue light">
<span>off</span>
<span>on</span>
</div>
Option 3: Refer to another element using aria-labelledby
Use the aria-labelledby
attribute to identify another element, using its ID, to serve as the name for the current element.
For example, this custom menu radio button refers to the menuitem1Label
paragraph as its label and will be announced as "Sans-serif":
<p id="menuitem1Label">Sans-serif</p>
<ul role="menu">
<li id="menuitem1"
role="menuitemradio"
aria-labelledby="menuitem1Label"
aria-checked="true"></li>
</ul>
Example 2: How to add accessible names to your custom ARIA input fields
The easiest way to provide an accessible name for most elements is to include text content in the element. However, custom input fields typically don't have inner text, so you can use one of the following strategies instead.
Option 1: Add an aria-label
attribute to the element
Use the aria-label
attribute to define the name for the current element.
For example, this custom combobox will be announced as "country" to assistive technology users:
<div id="combo1" aria-label="country" role="combobox"></div>
Option 2: Refer to another element using aria-labelledby
Use the aria-labelledby
attribute to identify another element, using its ID, to serve as the name for the current element.
For example, this custom searchbox refers to the searchLabel
paragraph as its label and will be announced as "Search currency pairs":
<p id="searchLabel">Search currency pairs:</p>
<div id="search"
role="searchbox"
contenteditable="true"
aria-labelledby="searchLabel"></div>
Resources
- Source code for Not all ARIA toggle fields have accessible names audit
- ARIA button, link, and menuitem must have an accessible name (Deque University)
- ARIA input fields must have an accessible name (Deque University)
- ARIA meter must have an accessible name (Deque University)
- ARIA progressbar must have an accessible name (Deque University)
- ARIA toggle fields have an accessible name (Deque University)
- ARIA tooltip must have an accessible name (Deque University)
- ARIA treeitem must have an accessible name (Deque University)
- Labels and text alternatives
- Use semantic HTML for easy keyboard wins