Axe Core Guide
IDs of active elements must be unique
The value supplied to active ID attributes on focusable elements must be unique to avoid assistive technology from overlooking the second instance. Active ID attributes may not be used more than once on focusable components inside the same document; assistive technology requires unique IDs for focusable active elements in order to differentiate between them.
Focusable components on a page are identified exclusively by the ID attribute. It is illogical to duplicate an active ID.
Duplicate active ID values compromise the accessibility of focusable elements, such as form labels, table header cells, and so on. Screen readers and client-side scripts will bypass all instances of repetition other than the first. Validating HTML files aids in preventing and eliminating potential sources of accessibility issues, so long as accessibility is not compromised.
Those who have expertise with client-side scripting are aware that when an active ID is reused, the only instance that is normally acted upon by the script is the first. Similarly, assistive technology may only appropriately reference the first active ID when mentioning it.
What this Accessibility Rule Checks
Ensures that each page element with an active ID and a focusable state has a unique value.
Learn more:
Related Accessibility Rules
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.
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.
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.
Each page must have a main
landmark to allow users to rapidly traverse repetitive blocks of material or interface elements (such as the header and navigation) and get the primary content.
Due to the fact that websites frequently display secondary, repetitive content on several pages (such as navigation links, heading graphics, and advertising frames), keyboard-only users benefit from faster, more direct access to a page’s principal content. This saves keystrokes and reduces physical discomfort.
It is more difficult and time-consuming for users who cannot use a mouse to navigate using the keyboard if the interface does not provide features to facilitate keyboard navigation. To activate a link in the middle of a web page, for instance, a keyboard user may have to browse through a significant number of links and buttons in the page’s header and primary navigation.
Extremely motor-impaired users may require several minutes to browse through all of these pieces, which can cause to tiredness and potential physical pain for some users. Even users with less severe limitations will require more time than users with a mouse, who can click on the desired link in less than a second.
What this Accessibility Rule Checks
Checks for the presence of at least one of the following features:
- an internal skip link
- a header
- a geographical landmark
Definition lists (dl
) may only contain dt
and dd
groups, div
, script
, or template
elements that are properly organized.
Screen readers have a particular method for reading definition lists. When such lists are not correctly marked up, screen reader output may be erroneous or confusing.
A list of definitions is used to explain the meaning of words or phrases. Using the dl
element, the definition list is formatted. Within the list, each term is enclosed in its own dt
element, and its definition is enclosed in the dd
element that immediately follows.
What this Accessibility Rule Checks
Ensures that each dl
element is correctly constructed.
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.
The title
element of the HTML document must not be empty in order to give users with an overview of its content.
Users using screen readers utilize page titles to obtain an overview of the page’s content. If a page lacks a title, navigating through it can soon become difficult and confusing for screen reader users. The title
element of the page is the first item screen reader users hear when the page loads.
When they arrive at a page, screen reader users hear the page’s title first. If there is no title
or if the title
is not descriptive and unique, users of screen readers must read the page to discern its content and purpose.
What this Accessibility Rule Checks
Makes certain that each HTML document has a title
tag associated with it.