Learn Measure Blog About

ARIA toggle fields 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. Native 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 native HTML controls and custom ARIA controls must have accessible names that convey their purpose.

How Lighthouse identifies ARIA toggle fields without accessible names

Lighthouse flags custom ARIA toggle fields whose names aren't accessible to assistive technologies:

Lighthouse audit showing custom toggle elements without accessible names

Elements that have any of the following ARIA roles but don't have accessible names will cause this audit to fail:

This audit is similar to the Not all ARIA input fields have accessible names audit but checks a different set of ARIA roles.

Caution: Most common input types can be created with native HTML elements, which come with built-in behaviors and accessible semantics that can be time consuming to replicate. Consider using native 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.

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>

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>

Resources

Last updated: Improve article