Axe Core Guide

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.

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.

Ensures every ARIA input field has an accessible name.

This rule ensures that each ARIA input field has a name that is accessible.

There must be accessible names for the following input field roles:

• combobox
• listbox
• searchbox
• slider
• spinbutton
• textbox

What this Accessibility Rule Checks

The names of ARIA input fields must be accessible.

Not all ARIA role-attribute combinations are valid. Elements must only use permitted ARIA attributes.

Using ARIA attributes in roles where they are prohibited can mean that important information is not communicated to users of assistive technologies. Assistive technologies may also attempt to compensate for the issue, resulting in inconsistent and confusing behavior of these tools.

This Rule checks that noe of the attributes used with a particular role are listed as “prohibited” for that role in the latest version of WAI-ARIA.

The aria-label and aria-labelledby attributes are prohibited on presentation and none roles, as well as on text-like roles such as code, insertion, strong, etc.

What this Accessibility Rule Checks

Checks that each ARIA attribute used is not described as prohibited for that element’s role in the WAI-ARIA specification.

Ensures that the aria-roledescription attribute is only applied to elements having explicit or implicit role values.

Inappropriate aria-roledescription attribute values that clash with an element’s implicit or explicit role value can impede the web page’s accessibility. A contradictory aria-roledescription attribute value may have no effect on the application’s accessibility and may trigger behavior that blocks accessibility for entire application sections.

When aria-roledescription attributes are applied to HTML elements not in accordance with WAI-ARIA 1.1, a semantic conflict may occur between the aria-roledescription value and the implicit or explicit element role value, resulting in assistive technology products reporting nonsensical user interface (UI) information that does not accurately represent the intended UI experience.

What this Accessibility Rule Checks

Use aria-roledescription values to adequately explain implicit or explicit element role values.

Makes certain that each ARIA toggle field has an accessible name.

Ensures that any element having a semantic role has a name that is easily accessible.

Among the semantic roles are:

• checkbox
• menu
• menuitemcheckbox
• menuitemradio
• radio
• radiogroup
• switch

What this Accessibility Rule Checks

There is an accessible name for ARIA toggle fields.

To be valid, definition list items (dt and / or dd) must be enclosed by parent dl elements. This allows screen reader users to recognize the right hierarchy of the list’s information.

A definition list item is invalid if it is not surrounded by parent dl elements.

A definition list must adhere to a particular hierarchy. Using the dl element, a list is defined. It is followed by alternating sets of dt and dd elements, beginning with dt. dt elements define a term while dd elements denote a term’s description. Each group of dt components must be accompanied by a group of dd elements. In the definition list, only dt and dd items are permitted. If not followed, this hierarchy will render the list invalid.

What this Accessibility Rule Checks

Ensures that every child dd and dt element has a parent dl element.

To help screen reader users understand the contents of each frame or iframe element in the document, each element must have a distinct title.

A frame title is used by screen reader users to describe the contents of the frame. If the frames are not identified with a title element, navigating across frames and iframes can soon become challenging and confusing for users of this technology.

Users of screen readers can choose to display a list of all the titles for the frames on a page. Users can locate the frame they’re looking for more quickly by adding descriptive, distinctive labels. Without titles, moving between frames can become challenging and perplexing very quickly. Screen readers will instead provide information such as “frame,” “javascript,” the filename, or the URL if there is no title specified. This information won’t usually be particularly useful.

What this Accessibility Rule Checks

Make sure that the title attribute on every iframe and frame element is distinct and not empty.

When used in a document, the frame or iframe element’s title attribute must not be empty in order to provide context for users of screen reader software.

Users of screen readers depend on the title of a frame to describe its contents. If the HTML for a frame or iframe element lacks a title attribute, navigating within the element can be a frustrating and time-consuming experience for users of this technology.

Users of screen readers can see a list of the frames on a page and their respective titles. Providing each frame with a distinct, descriptive label facilitates easy navigation. Without titles, it’s easy to get lost trying to jump from one frame to the next. Screen readers will instead provide information like “frame,” “JavaScript,” the filename, or the URL if no title is provided. This data is unlikely to be useful in most situations.

What this Accessibility Rule Checks

Make sure the title attribute of every iframe and frame element is both distinct and not empty.

When used as links, link text and alternative text for images must be recognizable by screen readers, have no duplicate labels, and be focusable.

• Accessibility is hindered by inaccessible link components, as they are a crucial component of a website.
• Users who traverse a webpage using only the keyboard (and no mouse) can only click on links that can gain programmed emphasis. Inaccessible to these users is any link that cannot gain programmatic focus.
• Similar to sighted people, screen reader users must know where a link leads. This information is provided via inner link text, albeit it will not be utilized if a screen reader cannot access it.
• Only the links and form components that can get programmatic focus can be activated by keyboard users, including those with visual impairments or those who cannot use a mouse. Keyboard users cannot access events activated only by other sorts of focus, such as onmouseover events that depend on the mouse hover focus. By default, only links and form elements receive keyboard emphasis. Add tabindex="0" to items that are not links or form components to make them focusable.

What this Accessibility Rule Checks

Ensures that each link’s name is accessible.