Axe Core Guide
Elements must have their visible text as part of their accessible name
The visible label of interactive items labeled through their content must be included in their accessible name.
This rule applies to any element with the following attributes:
- a semantic role that is a widget that supports name from content,
- visible text, and
-
an
aria-labeloraria-labelledbyattribute.
button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, radio, searchbox, switch, tab, and treeitem are widget roles that support name from content.
The whole visible text content of the target element either matches its accessible name or is contained within it.
Leading and trailing whitespace and case sensitivity differences should be disregarded.
Users using speech input can interact with a web page by saying the visible text labels of menus, links, and buttons.
Voice input users are confused when they utter a visible text label, but the speech command does not work since the accessible (programmatic) name of the component does not match the visible label. When a user interface component contains a visible text label — whether the label is actual text or a picture of text — that text must also appear in the component’s accessible (programmatic) name. When the visual label and accessible (programmatic) name for interactive components are synchronized, users using speech input can engage with those components successfully.
What this Accessibility Rule Checks
For any user interface element with a visible text label, the accessible name must match (or include) the label’s visible text.
Learn more:
- Deque University - How To Fix
- WCAG 2.1 - Success Criterion 2.5.3 Label in Name
- WCAG 2.1 - Failure of Success Criterion 4.1.2 due to a user interface control not having a programmatically determined name
- WCAG 2.1 - Using label elements to associate text labels with form controls
- WCAG 2.1 - Using aria-labelledby to provide a name for user interface controls
- WCAG 2.1 - Using aria-label to provide an invisible label where a visible label cannot be used
- WCAG 2.1 - Using the title attribute to identify form controls when the label element cannot be used
Related Accessibility Rules
Elements with aria-hidden must not contain focusable elements.
Using the property aria-hidden="true" on an element removes the element and all of its child nodes from the accessibility API, rendering the element fully unavailable to screen readers and other assistive technology.
aria-hidden may be used with extreme discretion to hide visibly displayed content from assistive technologies if the act of hiding this content is meant to enhance the experience of assistive technology users by reducing redundant or superfluous content.
If aria-hidden is employed to hide material from screen readers, the same or equal meaning and functionality must be made available to assistive technologies.
Using aria-hidden="false" on content that is a descendant of an element that is hidden using aria-hidden="true" will not reveal that content to the accessibility API, nor will it be accessible to screen readers or other assistive technology.
The rule applies to any element whose aria-hidden attribute value is true.
By adding aria-hidden="true" to an element, authors assure that assistive technologies will disregard the element.
This can be used to hide aesthetic elements, such as icon typefaces, that are not intended to be read by assistive technologies.
A focusable element with aria-hidden="true" is disregarded as part of the reading order, but is still part of the focus order, making it unclear if it is visible or hidden.
What this Accessibility Rule Checks
For all user interface components, including form elements, links, and script-generated components, the name and role can be identified programmatically; user-specified states, properties, and values can be set programmatically; and user agents, including assistive technologies, are notified of changes.
The list of 53 Input Purposes for User Interface Components are used as the basis for the programmatic definition of the purpose for each common input field that collects user data.
For screen readers to work properly, the autocomplete attribute values must be true and applied correctly.
Inaccessible content stems from missing autocomplete values in form fields. In the absence of the necessary autocomplete attribute values, screen readers will not read the identified autocomplete form fields.
When screen readers are unable to adequately notify users about the requirements for form field interaction, users cannot successfully navigate forms.
What this Accessibility Rule Checks
The purpose of each user-information-collecting input field can be established programmatically when:
- The input field fulfills a purpose specified in the Input Purposes for User Interface Components section, and
- The content is implemented using technologies that provide support for determining the desired meaning of form input data.
Makes certain that a form field doesn’t have multiple labels.
For some combinations of screen readers and browsers, adding several labels to the same form field can result in issues, and the outcomes vary depending on the combination. The first label will be read by some combinations. The last label will be read by some. Both labels will be read by others.
What this Accessibility Rule Checks
Makes certain that a form field doesn’t have multiple labels.
Each form element must have a label element attached with it programmatically.
Forms must have effective form labels in order to be accessible. Form elements like as checkboxes, radio buttons, input fields, etc. are frequently self-explanatory to sighted users, even if they are not programmatically labeled. Users with screen readers require descriptive form labels to identify form fields. Adding labels to all form elements removes uncertainty and makes the product more accessible.
When form elements lack labels, screen reader users are unaware of the expected data input. Screen readers cannot determine information about input items programmatically in the absence of an established label association (or redundant text functioning as a label).
Since clicking the label activates the control, people with weak motor control do not benefit from a bigger clickable area for the control.
What this Accessibility Rule Checks
Ensures that each form element has a label associated with it programmatically.
Since screen reader users cannot otherwise determine the structure of the document, styled p components must not be utilized to represent headings.
The fundamental goal of headers is to communicate the page’s organizational structure. Using varied text sizes allows sighted readers to see the structure. However, heading components must be marked up properly for screen reader users.
When header components are used correctly, both sighted and screen reader users will find it much simpler to traverse the page.
Users of screen readers can navigate between headings in the same manner that sighted users might skim a page to gain a sense of its contents. Users, especially those who use screen readers, can save a ton of time and stress by using well-written, logically-arranged headings.
Headings serve to explain the organization of the webpage, not only to draw attention to key text. They must be succinct, distinct, and numbered h1 through h6 in hierarchical sequence. For screen reader users, headers are a useful tool because of all of these characteristics.
Users of screen readers can navigate between headings in the same manner that sighted users might skim a page to gain a sense of its contents. Users, especially those who use screen readers, can save a ton of time and stress by using well-written, logically-arranged headings.
Due to the fact that search engines use headings when filtering, arranging, and showing results, headers offer advantages beyond just making a page more accessible. Making your website more searchable is another benefit of making it more accessible.
What this Accessibility Rule Checks
Verifies that paragraph components are not given the appearance of headers by using italic, bold, or font size.
An image map consists of a single image with numerous clickable sections. Because screen readers cannot translate graphics into text, an image map, like all images, must contain alternative text for each of the distinct clickable parts, as well as for the larger image itself.
In the absence of alternative text, screen readers often announce the image’s filename. Filenames do not accurately describe images and are therefore inconvenient for screen reader users.
What this Accessibility Rule Checks
Ensures that image map area elements have alternative text.
Not all ARIA role-attribute combinations are valid. This rule ensures that each role has the required qualities.
Using ARIA attributes in roles where they are not permitted can impair web page accessibility. Using an improper role-attribute combination will have no effect on application accessibility at best and may trigger behavior that blocks accessibility for entire areas of an application at worst.
When ARIA attributes are used on HTML elements that do not conform to WAI-ARIA 1.1, they interfere with the semantics of the elements, causing assistive technology products to display nonsensical user interface (UI) information that does not represent the document’s true UI.
What this Accessibility Rule Checks
Checks that each element with an ARIA role is using only the ARIA attributes that are permitted for that role.
The destination, purpose, function, or action of an ARIA command element must be made clear in understandable text for screen reader users.
The function of items with the roles link, button, or menuitem that lack an accessible name cannot be understood by screen reader users.
What this Accessibility Rule Checks
Verifies that all elements with the roles link, button, or menuitem have a clear, understandable name.
ARIA attributes must be used as specified for the element’s role.
Using ARIA attributes on elements where they are not expected can result in unpredictable behavior for assistive technologies. This can lead to a poor user experience for people with disabilities who rely on these technologies. It is important to follow the ARIA specification to ensure that assistive technologies can properly interpret and communicate the intended meaning of the content.
Some ARIA attributes are only allowed on an element under certain conditions. Different attributes have different limitations to them:
aria-checked: This should not be used on an HTML input element with type=”checkbox”. Such elements have a checked state determined by the browser. Browsers should ignore aria-checked in this scenario. Because browsers do this inconsistently, a difference between the native checkbox state and the aria-checked value will result in differences between screen readers and other assistive technologies.
The aria-posinset, aria-setsize, aria-expanded, and aria-level attributes are conditional when used on a row. This can be either tr element, or an element with role="row". These attributes can only be used when the row is part of treegrid. When used inside a table or grid, these attributes have no function, and could result in unpredictable behavior from screen readers and other assistive technologies.
What this Accessibility Rule Checks
Check that ARIA attributes are not used in a way that their role describes authors should not, or must not do. I.e the use of this ARIA attribute is conditional.
Values assigned to ARIA role values must not be deprecated.
Using deprecated WAI-ARIA roles is bad for accessibility. They will not be recognized or correctly processed by screen readers and other assistive technologies. Using these means not everyone will be able to access essential information.
Ensure all values assigned to role="" correspond to WAI-ARIA roles that are not deprecated, or abstract. The following list indicates for each deprecated role a potential alternative that is better supported by assistive technologies:
-
directory: Consider using
section,list, ortreeinstead. Which is most appropriate depends on how directory was used.
What this Accessibility Rule Checks
Check all elements containing WAI-ARIA role attribute to ensure that the role is not deprecated in the latest version of the WAI-ARIA specification.