This document provides information about the related accessibility checks:
Visible label is part of accessible name
What
The visible label of any widget, such as buttons or checkboxes, must match or be included in the element's accessible name.
Note
A widget is an interactive UI component, such as a button, slider, or checkbox, that allows user interaction as defined in ARIA specifications. The visible label is the text or element users see on the screen, such as the text on a button. The accessible name is the name announced by assistive technologies, like screen readers, and can be derived from the visible label, ARIA attributes, or HTML elements like alt or title.
Why
When the visible label of an interactive element, such as a button or checkbox, does not match or is not included in its accessible name, it can create significant barriers for users who rely on voice recognition software. These users interact with web content by speaking commands that correspond to the visible labels on the screen. If the accessible name differs from what is visually presented, the software may not recognize the verbal command. This makes it impossible to activate the desired element. For example, if a button displays Start but the accessible name is Begin Process, a voice command that says "Click Start" will not work. This mismatch can hinder the user’s ability to navigate and complete tasks efficiently. Ensure that the visible label is part of the accessible name to allow voice recognition software to function correctly and to provide a seamless and accessible experience for all users.
This check affects the following users who have
Motor impairments: Who use alternative input methods, such as voice control, due to limited hand mobility.
Vision impairments: Who use screen readers to access the names of interactive elements.
User story
Sandra is 38 years old. At the age of 16, her life took an unexpected turn during a sports accident on the basketball court. While attempting a daring dunk, she landed in an awkward manner, resulting in a spinal cord injury. Unfortunately, this event left her paralyzed from the waist down.
"I rely on dictation software to navigate websites because using a mouse for too long causes me pain. But sometimes, I tell the software to 'Click Submit,' and nothing happens because the button has a different label in the code like 'Send Form.' It is frustrating when simple tasks become impossible just because what I see does not match what the software recognizes. It might seem small, but when you face this all the time, it really adds up."
Examples
This section gives some examples of the issue.
Example – Link with mismatched visible text and accessible name
A webpage contains a link with visible text that differs from the accessible name set by the aria-label attribute.
In this case, the visible text is Web Content Accessibility Guidelines, but the accessible name is set to WCAG.
This mismatch can cause issues for users who rely on voice recognition software. For instance, if a user gives the command "Click Web Content Accessibility Guidelines," the software does not recognize the instruction because it references the visible text, not the accessible name. This inconsistency can lead to frustration and hinder users from accessing the intended link effectively.
Example: Link with matching visible text and accessible name
A webpage contains a link where the visible text is included in the accessible name set by the aria-label attribute.
In this case, the visible text is Web Content Accessibility Guidelines, and the accessible name is Web Content Accessibility Guidelines (WCAG).
Since the visible label is included in the accessible name, users who rely on voice recognition software can successfully activate the link by saying "Click Web Content Accessibility Guidelines." This consistency ensures a smooth and accessible user experience for those users who navigate through speech commands.
How
How to fix it.
The Web Governance platform highlights elements that have a semantic role as a widget supporting name from content. It flags these elements if they have visible text content and include an aria-label or aria-labelledby attribute, but the visible label is not part of the accessible name.
Note
A widget is an interactive UI component, such as a button, slider, or checkbox, defined by ARIA roles to support user interaction. A name from content means the accessible name of the element is derived directly from its visible text or content. For more details, you can refer to the WAI-ARIA specification.
To fix the error, adjust the name set in the aria-label or aria-labelledby so that it matches or at least includes the visible text from the element, as shown in the example section on this page.
For more information, see the ACT rules section below, which includes a link to a complete technical explanation of this check.
This document provides information about the related accessibility checks:
Visible label is part of accessible name
What
The visible label of any widget, such as buttons or checkboxes, must match or be included in the element's accessible name.
Note
A widget is an interactive UI component, such as a button, slider, or checkbox, that allows user interaction as defined in ARIA specifications. The visible label is the text or element users see on the screen, such as the text on a button. The accessible name is the name announced by assistive technologies, like screen readers, and can be derived from the visible label, ARIA attributes, or HTML elements like alt or title.
Why
When the visible label of an interactive element, such as a button or checkbox, does not match or is not included in its accessible name, it can create significant barriers for users who rely on voice recognition software. These users interact with web content by speaking commands that correspond to the visible labels on the screen. If the accessible name differs from what is visually presented, the software may not recognize the verbal command. This makes it impossible to activate the desired element. For example, if a button displays Start but the accessible name is Begin Process, a voice command that says "Click Start" will not work. This mismatch can hinder the user’s ability to navigate and complete tasks efficiently. Ensure that the visible label is part of the accessible name to allow voice recognition software to function correctly and to provide a seamless and accessible experience for all users.
This check affects the following users who have
Motor impairments: Who use alternative input methods, such as voice control, due to limited hand mobility.
Vision impairments: Who use screen readers to access the names of interactive elements.
User story
Sandra is 38 years old. At the age of 16, her life took an unexpected turn during a sports accident on the basketball court. While attempting a daring dunk, she landed in an awkward manner, resulting in a spinal cord injury. Unfortunately, this event left her paralyzed from the waist down.
"I rely on dictation software to navigate websites because using a mouse for too long causes me pain. But sometimes, I tell the software to 'Click Submit,' and nothing happens because the button has a different label in the code like 'Send Form.' It is frustrating when simple tasks become impossible just because what I see does not match what the software recognizes. It might seem small, but when you face this all the time, it really adds up."
Examples
This section gives some examples of the issue.
Example – Link with mismatched visible text and accessible name
A webpage contains a link with visible text that differs from the accessible name set by the aria-label attribute.
In this case, the visible text is Web Content Accessibility Guidelines, but the accessible name is set to WCAG.
This mismatch can cause issues for users who rely on voice recognition software. For instance, if a user gives the command "Click Web Content Accessibility Guidelines," the software does not recognize the instruction because it references the visible text, not the accessible name. This inconsistency can lead to frustration and hinder users from accessing the intended link effectively.
Example: Link with matching visible text and accessible name
A webpage contains a link where the visible text is included in the accessible name set by the aria-label attribute.
In this case, the visible text is Web Content Accessibility Guidelines, and the accessible name is Web Content Accessibility Guidelines (WCAG).
Since the visible label is included in the accessible name, users who rely on voice recognition software can successfully activate the link by saying "Click Web Content Accessibility Guidelines." This consistency ensures a smooth and accessible user experience for those users who navigate through speech commands.
How
How to fix it.
The Web Governance platform highlights elements that have a semantic role as a widget supporting name from content. It flags these elements if they have visible text content and include an aria-label or aria-labelledby attribute, but the visible label is not part of the accessible name.
Note
A widget is an interactive UI component, such as a button, slider, or checkbox, defined by ARIA roles to support user interaction. A name from content means the accessible name of the element is derived directly from its visible text or content. For more details, you can refer to the WAI-ARIA specification.
To fix the error, adjust the name set in the aria-label or aria-labelledby so that it matches or at least includes the visible text from the element, as shown in the example section on this page.
For more information, see the ACT rules section below, which includes a link to a complete technical explanation of this check.
Web Governance