Axe Core Guide
HTML elements with lang and xml:lang must have the same base language
For multilingual screen reader users who may prefer a language different than the default, the HTML content must contain a valid lang
attribute or correlate to a valid lang
code. If included on the html
element, the xml:lang
property value must exactly duplicate the value of the lang
.
Users choose a default language when configuring a screen reader. If the language of a webpage is not provided, the screen reader uses the user’s default language. Users who speak and access websites in various languages have difficulties. For screen readers to function properly, a default language must be specified and ensured to be valid.
Screen readers employ various sound libraries for each language based on its pronunciation and characteristics. Screen readers can simply switch between language libraries if documents specify which language(s) should be read. Screen readers view texts in the user’s default language if the language is not specified, resulting in distorted language. When screen readers use the incorrect language library, it can be difficult to understand anything.
What this Accessibility Rule Checks
Ensures that every HTML document includes a valid lang
attribute, and that the xml:lang
value, if present, replicates the lang value.
Learn more:
Related Accessibility Rules
Ensures that video
or audio
elements don’t have autoplay audio that lasts more than three seconds without a way to silence it.
When using screen reading software, people who are blind or have low vision may have trouble hearing the screen reader’s spoken output if other audio is playing at the same time.
If automatically playing audio continues for more than three seconds, it must be possible to pause, stop, or adjust the level using a well placed, easily accessible mechanism.
Users of screen readers can hear the screen reader without any other sounds playing thanks to an audio control.
A screen reader user’s ability to find the stop button may be hampered if audio starts playing immediately when they land on a page. This is because they navigate by listening, and automatically starting sounds may obstruct that navigation.
Therefore, we oppose the practice of automatically starting sounds (especially if they run longer than three seconds) and encourage users to start the sound themselves once they arrive at the page rather than expecting them to stop the sound themselves once they have reached the page.
What this Accessibility Rule Checks
The algorithm for this rule returns:
-
Undefined when
<audio>
has no source (duration cannot be interpreted). -
Undefined when
<video>
has no source (duration cannot be interpreted). -
False when
<audio>
can autoplay and has no controls mechanism. -
False when
<video>
can autoplay and has no controls mechanism -
False when
<audio>
plays less than three seconds but loops. -
True when
<video>
can autoplay and duration is less than three seconds (by passing options). -
True when
<video>
can autoplay and duration is below allowed duration (by setting playback range). -
True when
<audio>
can autoplay but has controls mechanism. -
True when
<video>
can autoplay and has controls mechanism.
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.
For multilingual screen reader users who would prefer a language other than the default, the HTML document element must have a valid lang
property or match to a valid lang
code.
The default language is chosen by users when setting up a screen reader. The screen reader uses the user’s default language preference when a webpage’s language is not specified. When people visit websites in more than one language and speak various languages, language settings become a problem. To ensure that website text is pronounced accurately, a language must be specified and validated.
Based on the pronunciation and traits of each language, screen readers employ distinct sound libraries for each one. If the documents state which language(s) to read when, screen readers can effortlessly switch between these language libraries. The screen reader will read the page in the user’s default language if the language is not set, which will result in an odd accent. When screen readers are utilizing the incorrect language library, nothing can be understood.
What this Accessibility Rule Checks
Ensures that the lang
attribute is present in every HTML document.
For multilingual screen reader users who may prefer a language different than the default, the HTML content must contain a valid lang
attribute or correlate to a valid lang
code.
Users choose a default language when configuring a screen reader. If the language of a webpage is not provided, the screen reader uses the user’s default language. Language settings are a problem for users who speak different languages and visit websites in multiple languages. It is critical to declare a language and guarantee that it is valid in order for website text to be properly pronounced.
Screen readers employ various sound libraries for each language based on its pronunciation and characteristics. Screen readers can readily switch between these language libraries, but only if the documents specify which language(s) they should read. If no language is supplied, the screen reader reads the content in the user’s default language, which results in a perplexing accent! When screen readers use the incorrect language library, it is difficult to understand anything.
What this Accessibility Rule Checks
Ensures that every HTML document contains a lang
or xml:lang
property with a valid value.
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 alternate text for each of the distinct clickable parts, as well as for the larger image itself.
In the absence of alternate 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 alternate 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.
aria-braille
attributes must have a non-braille equivalent.
WAI-ARIA requires that the aria-braillelabel
attribute is only ever used on elements with an accessible name, such as from aria-label
. Similarly, aria-brailleroledescription
is required to only ever be used on elements with aria-roledescription
.
ARIA braille attributes were introduced to allow adjusting how labels and role descriptions are rendered on a braille display. They cannot be the only attribute providing a label, or a role description. When used without a corresponding label or role description ARIA says to ignore these attributes, although this may not happen consistently in screen readers and other assistive technologies.
How to Fix this Issue
-
The
aria-braillelabel
oraria-brailleroledescription
attribute may have been placed on the wrong element, such as a parent or child of the correct element. The attribute should be put on a different element. -
The element with
aria-braillelabel
attribute needs anaria-label
attribute or other attribute that gives it an accessible name. -
The element with
aria-brailleroledescription
attribute needs aaria-roledescription
attribute. -
The
aria-braillelabel
oraria-brailleroledescription
attribute serves no function and should be removed.
What this Accessibility Rule Checks
Checks that aria-braillelabel
is only used on elements with a non-empty label, and that aria-brailleroledescription
is only used on elements with a non-empty aria-roledescription
.
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
, ortree
instead. 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.
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.