Axe Core Guide

Ensure that the text spacing specified by style attributes is modifiable using custom stylesheets.

When lines of text are single-spaced, many people with cognitive difficulties have difficulty following them. Providing spacing between 1.5 and 2 makes it easier for them to begin a new line after finishing the previous one.

What this Accessibility Rule Checks

Text line spacing must be modifiable by custom stylesheets.

To guarantee that text is pronounced correctly for screen reader users, the language given in the HTML content must be one of the valid languages.

The default language is chosen by users when setting up a screen reader. The screen reader assumes that a webpage is in the user’s default language when the language is not selected. When visitors access the website in more than one language and speak various languages, choosing a language becomes problematic. 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 papers specify which language(s) to read, screen readers can quickly switch between these language libraries. The screen reader will read the content in the user’s default language if the language is not set, which can be confusing.

What this Accessibility Rule Checks

The value of the lang attribute must be correct.

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 screen orientation (such as portrait or landscape) of mobile applications should not be restricted to a single mode. Users should be able to shift the orientation of their device between portrait and landscape without losing readability. Additionally, upon opening a page, it should appear in the current orientation of the user.

Users of assistive technologies may not have access to orientation features on their devices or assistive technologies.

What this Accessibility Rule Checks

Unless a specific display orientation is important, content does not confine its view and functionality to a single display orientation, such as portrait or landscape.

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.

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-label or aria-labelledby attribute.

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.

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.

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.

The WAI-ARIA specification organizes roles, states, and properties into a strict taxonomy. Each role defines three categories of attributes it can use:

• Required attributes — must be present for the role to function correctly.
• Supported attributes — optionally enhance the role’s semantics.
• Inherited attributes — come from superclass roles in the ARIA role hierarchy.

Any ARIA attribute that doesn’t fall into one of these categories is not allowed on that role. This applies equally to explicit roles (set with the role attribute) and implicit roles that HTML elements carry by default. For instance, <button> has an implicit role of button, <input type="checkbox"> has an implicit role of checkbox, and <h2> has an implicit role of heading.

When an unsupported attribute appears on an element, the result is unpredictable. A screen reader might silently ignore it, or it might announce contradictory information — for example, describing a heading as a checkable control. In the worst case, invalid role-attribute combinations can break accessibility for entire sections of a page.

Who is affected

This issue has a critical impact on people who use assistive technologies:

• Screen reader users (blind and deafblind users) depend on accurate role and state information to understand and interact with content. Conflicting ARIA attributes can cause elements to be announced as something they are not.
• Voice control users rely on correctly exposed semantics to issue commands targeting specific controls. Misrepresented roles can make controls unreachable by voice.
• Users of switch devices and alternative input methods depend on tools that interpret ARIA roles and attributes to identify operable controls. Invalid attributes can make controls appear inoperable or misrepresent their purpose entirely.

When ARIA attributes conflict with an element’s role, these users may encounter controls that lie about what they do, states that never update correctly, or entire regions that become completely unusable.

Relevant WCAG success criteria

This rule relates to WCAG 2.0, 2.1, and 2.2 Success Criterion 4.1.2: Name, Role, Value (Level A), as well as EN 301 549 clause 9.4.1.2. This criterion requires that all user interface components expose their name, role, and value to assistive technologies in a way that can be programmatically determined. Using unsupported ARIA attributes on a role violates this criterion because it introduces properties that conflict with the element’s actual role, breaking the contract between the page and assistive technology.

How to fix the problem

1. Identify the element’s role. Check for an explicit role attribute. If none is present, determine the element’s implicit ARIA role from its HTML tag. For example, <input type="checkbox"> has an implicit role of checkbox, and <nav> has an implicit role of navigation.

2. Look up the allowed attributes for that role in the WAI-ARIA specification’s role definitions. Each role page lists its required states and properties, supported states and properties, and inherited properties from superclass roles.

3. Remove or relocate any ARIA attribute that isn’t in the allowed list. If the attribute belongs on a different element within your component, move it there.

4. Reconsider the role. Sometimes the right fix isn’t removing the attribute but changing the element’s role to one that supports the attribute you need. If you want a toggleable control, use role="switch" or role="checkbox" instead of role="button".

5. Consult the ARIA in HTML specification for additional conformance rules about which ARIA attributes are appropriate on specific HTML elements, including restrictions on how elements can be named.

Examples

Incorrect: unsupported attribute on an explicit role

The aria-checked attribute is not supported on role="textbox" because a textbox is not a checkable control. A screen reader might announce this element as both a text input and a checked control.

<div role="textbox" aria-checked="true" contenteditable="true">
  Enter your name
</div>

Correct: unsupported attribute removed

Remove aria-checked since it has no meaning on a textbox. Use aria-label to provide an accessible name.

<div role="textbox" contenteditable="true" aria-label="Your name">
</div>

Incorrect: unsupported attribute on an implicit role

The <h2> element has an implicit role of heading. The aria-selected attribute is not supported on headings because headings are not selectable items.

<h2 aria-selected="true">Account Settings</h2>

Correct: unsupported attribute removed from heading

If selection semantics aren’t needed, remove the attribute. If you need selection behavior, use an element with an appropriate role such as tab.

<h2>Account Settings</h2>

Incorrect: role doesn’t match the intended behavior

The developer wants a toggleable control but used role="button", which does not support aria-checked.

<div role="button" aria-checked="true" tabindex="0">
  Dark mode
</div>

Correct: role changed to one that supports the attribute

Changing the role to switch makes aria-checked valid. The element remains keyboard-operable via tabindex="0".

<div role="switch" aria-checked="true" tabindex="0" aria-label="Dark mode">
  Dark mode
</div>

Incorrect: unsupported attribute on a native HTML element

The <a> element has an implicit role of link. The aria-required attribute is not supported on links because links are not form fields that accept input.

<a href="/terms" aria-required="true">Terms of Service</a>

Correct: unsupported attribute removed from link

Remove aria-required from the link. If you need to indicate that agreeing to terms is mandatory, communicate that through a form control such as a checkbox.

<a href="/terms">Terms of Service</a>

Correct: supported attribute on a matching implicit role

The aria-expanded attribute is supported on the implicit button role, making this combination valid.

<button aria-expanded="false" aria-controls="menu-list">
  Menu
</button>
<ul id="menu-list" hidden>
  <li><a href="/home">Home</a></li>
  <li><a href="/about">About</a></li>
</ul>

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.