Accessibility Insights

Back to Info and Examples for Accessibility Insights for Web

aria-toggle-field-name

ARIA toggle fields must have accessible names.

Why it matters

An ARIA toggle field is a custom control that allows users to toggle its checked value. ARIA toggle fields are identified by the following ARIA role attributes:

  • checkbox
  • menuitemcheckbox
  • menuitemradio
  • radio
  • switch

An accessible name is a word or phrase coded in a way that assistive technologies can associate it with a specific user interface object. Assistive technologies can then refer to the object by name, not just by type. Unlike a standard HTML control, an ARIA toggle field requires additional markup to ensure it has an accessible name that conveys its purpose to users of assistive technologies.

How to fix

Provide an accessible name for each ARIA toggle field using ONE of the following methods.

Good

  • title attribute

Better

  • aria-label attribute
  • aria-labelledby attribute

Best

  • Inner text that’s available to assistive technologies (not marked with display: none or aria-hidden="true" )
  • <label> element (applies only to controls based on form elements)

Example

 

Fail

This code (together with scripting that isn't shown) functions as a switch. A <label> element is used in an attempt to give the switch an accessible name. However, the <label> element is valid HTML only when used with form elements, so no programmatic association has been made between the <span> and <label> elements. As a result, the switch has no accessible name, and people who use assistive technologies don't know its purpose.
<label for="dark-theme">Dark theme</label>
<span id="dark-theme" type role="switch" aria-checked="false" tabindex="0"></span>
 

Pass

The <label> element is changed to a <p> with an id, and the <span> is given an aria-labelledby attribute that refers to the id of the <p>. A programmatic association between the <span> and <p> elements is successfully created, so the switch has an accessible name. Assistive technologies can tell users that the switch toggles the dark theme.
<p id="dark-label">Dark theme</p>
<span id="dark-theme" role="switch" aria-checked="false" tabindex="0" aria-labelledby="dark-label"></span>

About this rule

This rule passes if:

  • ANY of the following are true:

    • Element has a non-empty aria-label attribute
    • Element has an aria-labelledby attribute that references elements that are visible to screen readers
    • Element has a non-empty title attribute
    • Element has text that is visible to screen readers

  • AND the following is true:

    • There is no mismatch between the element’s <label> and its accessible name

More examples

Understanding Success Criterion 1.3.1 Info and Relationships

Understanding Success Criterion 4.1.2: Name, Role, Value