Axe Core Guide
The id attribute serves as a unique identifier for an element within an HTML document. When id values are duplicated on active, focusable elements (elements that can receive keyboard focus, like inputs, buttons, links, and elements with tabindex), it creates a fundamental problem: the browser and assistive technologies have no reliable way to distinguish one element from another. This is different from duplicate IDs on non-focusable elements — while still invalid HTML, duplicate IDs on focusable elements have a more direct and serious impact on accessibility.
Why this matters
Screen readers rely on unique id values to build their internal model of the page. When a label references an id via the for attribute, or when aria-labelledby or aria-describedby points to an id, the assistive technology will typically only resolve the first element with that id. This means:
-
Form labels may point to the wrong control. A
<label>usingforto reference a duplicatedidwill only be associated with the first matching element. The second form control becomes unlabeled for screen reader users. -
ARIA relationships break. Attributes like
aria-labelledby,aria-describedby, andaria-controlsdepend on unique IDs to function correctly. -
Table header associations fail. When
<td>elements use theheadersattribute to reference<th>elements byid, duplicated IDs cause incorrect or missing header announcements. -
Client-side scripts malfunction. JavaScript methods like
document.getElementById()return only the first matching element, so event handlers and dynamic behavior may not apply to the intended element.
Users who are blind or deafblind are most seriously affected, as they depend entirely on assistive technology to navigate and interact with focusable elements. The user impact of this issue is considered serious.
While WCAG 2.0’s Success Criterion 4.1.1 (Parsing) originally required valid markup including unique IDs, this criterion was deprecated in WCAG 2.2 because modern browsers handle parsing errors more consistently. However, duplicate active IDs still cause real accessibility failures — particularly violations of SC 1.3.1 (Info and Relationships) and SC 4.1.2 (Name, Role, Value) — because they break the programmatic associations that assistive technology depends on.
How to fix it
-
Identify all focusable elements with duplicate
idvalues. You can use the axe accessibility checker, browser developer tools, or the W3C HTML Validator to find duplicates. -
Assign a unique
idto each focusable element. Append a distinguishing suffix, use a naming convention, or generate unique identifiers. -
Update all references to the renamed IDs, including
<label for="">,aria-labelledby,aria-describedby,aria-controls,headers, and any JavaScript that targets the element byid.
Examples
Incorrect: duplicate id on focusable elements
In this example, two input fields share the same id of "email". The label only associates with the first input, leaving the second input unlabeled for screen reader users.
<label for="email">Personal Email</label>
<input type="email" id="email" name="personal_email">
<label for="email">Work Email</label>
<input type="email" id="email" name="work_email">
Correct: unique id on each focusable element
Each input has a distinct id, and each label correctly references its corresponding control.
<label for="personal-email">Personal Email</label>
<input type="email" id="personal-email" name="personal_email">
<label for="work-email">Work Email</label>
<input type="email" id="work-email" name="work_email">
Incorrect: duplicate id breaking ARIA relationships
Here, two buttons share the same id, so aria-describedby on the dialog can only resolve to the first button — the description association for the second context is lost.
<button id="save-btn" aria-describedby="save-help">Save Draft</button>
<p id="save-help">Saves without publishing.</p>
<button id="save-btn" aria-describedby="publish-help">Save & Publish</button>
<p id="publish-help">Saves and makes content live.</p>
Correct: unique id values with proper ARIA references
<button id="save-draft-btn" aria-describedby="save-help">Save Draft</button>
<p id="save-help">Saves without publishing.</p>
<button id="save-publish-btn" aria-describedby="publish-help">Save & Publish</button>
<p id="publish-help">Saves and makes content live.</p>Learn more:
Last reviewed: February 14, 2026
Related Accessibility Rules
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
-
Identify the element’s role. Check for an explicit
roleattribute. If none is present, determine the element’s implicit ARIA role from its HTML tag. For example,<input type="checkbox">has an implicit role ofcheckbox, and<nav>has an implicit role ofnavigation. -
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.
-
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.
-
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"orrole="checkbox"instead ofrole="button". -
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>
WAI-ARIA role attribute values must be correct. This means that values must be written correctly, correlate to existing ARIA role values, and not be abstract roles in order to properly display the element’s purpose.
When an assigned WAI-ARIA role value for the parent element is invalid, a developer’s intended accessible technology activity is disabled.
When screen readers and other assistive devices do not understand the job of each element on a web page, they cannot interact with it intelligently or explain the role to the user. When the value for a role is invalid, assistive technologies are unable to communicate the element’s features, properties, and methods. Applying role="table" to a <ul>, for example, effectively hijacks the default semantics associated with the <ul> element in a way that screenreaders do not expect, resulting in unexpected behavior.
What this Accessibility Rule Checks
Check all elements with WAI-ARIA role attribute values to confirm the role value is correct. The role value must be appropriate for the element in the context of the document.
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-braillelabeloraria-brailleroledescriptionattribute 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-braillelabelattribute needs anaria-labelattribute or other attribute that gives it an accessible name. -
The element with
aria-brailleroledescriptionattribute needs aaria-roledescriptionattribute. -
The
aria-braillelabeloraria-brailleroledescriptionattribute 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, 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.
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.
ARIA widget roles must contain attributes describing the widget’s state or properties.
ARIA widget roles necessitate additional properties describing the widget’s state. If a needed attribute is missing, the widget’s status is not conveyed to users of screen readers.
Some roles function as composite user interface widgets. As such, they serve as containers that manage the widgets they contain. When an object inherits from several ancestors and one ancestor indicates support for a property and another says the property is required, the property becomes required on the inheriting object. In some circumstances, default values are sufficient to meet ARIA attribute requirements.
When required state and property attributes for specific roles (and subclass roles) are missing, screen readers may be unable to communicate the element’s role definition to the user.
What this Accessibility Rule Checks
Checks all elements with the role attribute to ensure that all necessary attributes are defined.