aria-allowed-attr
Web validation
WAI-ARIA defines which states and properties apply to each role. Using attributes that are not allowed for a given role creates conflicting semantics. Assistive technology users may hear misleading or contradictory announcements, which makes interfaces disorienting and hard to understand.
- Identify the element’s role. Prefer the implicit HTML role. Add an ARIA role only when needed.
- Look up the role’s allowed states and properties in the ARIA spec or “ARIA in HTML”.
- Keep only attributes that the role permits. Remove or replace all others.
- If a needed behavior requires different attributes, switch to the correct role or HTML element.
Pass Patterns
Checkbox with aria-checked
The checkbox role supports aria-checked to expose its checked state.
<div role="checkbox" aria-checked="false" tabindex="0">Subscribe</div>Toggle button with aria-pressed
A button exposes its toggle state with aria-pressed.
<button aria-pressed="false">Mute</button>Tab with aria-selected
The tab role supports aria-selected to indicate the active tab.
<div role="tab" aria-selected="true" id="t1">Overview</div>Textbox with aria-multiline
The textbox role supports aria-multiline to indicate it accepts multiple lines of text.
<div role="textbox" aria-multiline="true" contenteditable="true"></div>Fail Patterns
Button with aria-checked
The button role does not allow aria-checked. Use aria-pressed for toggle buttons.
<button aria-checked="true">Mute</button>Checkbox with aria-selected
The checkbox role does not allow aria-selected.
<div role="checkbox" aria-selected="true" aria-checked="true"></div>Tabpanel with aria-checked
The tabpanel role does not allow aria-checked.
<section role="tabpanel" aria-checked="true">Content</section>Textbox with aria-expanded
The textbox role does not allow aria-expanded unless it is part of a combobox pattern.
<div role="textbox" aria-expanded="true"></div>Edge cases:
- Global states and properties such as
aria-currentandaria-describedbyare allowed on any element so long as it is not marked as presentational. - Some attributes are valid only in specific patterns. Example:
aria-expandedis valid on arowonly if thatrowis within atreegrid. - If a custom widget keeps triggering this rule, the underlying role choice is likely wrong. Revisit the design.
ACT Rules
Try It Yourself
Using a screen reader
New to screen reader testing, or need a refresher?
Review this article first: Practical guides for using screen readers
- Turn on a screen reader.
- Navigate to the element.
- Listen for the role and any announced states (such as
aria-checked,aria-pressed, oraria-selected). - Toggle or change the control and confirm announcements remain consistent.
Expected results: The screen reader announces the correct role and only valid states for that role.
Actual results: If a disallowed attribute is used, the announcement can be missing, wrong, or conflicting.
Inspecting the browser dev-tools
- Open the element in the Elements panel.
- Review its implicit or explicit role.
- In the Accessibility panel, list all
aria-*attributes on the element. - Compare the attributes to the role’s allowed states and properties.
- Remove any disallowed attribute and recheck the Accessibility tree.
Expected results: The Accessibility panel shows the correct role with only permitted states and properties.
Actual results: If disallowed attributes are present, the panel may show unexpected or missing states, or contradictory information.
FAQ
How does this issue relate to 4.1.2 Name, role, value?
SC 4.1.2 requires user interface components to expose the correct name, role, and value. Disallowed ARIA attributes can override or conflict with the intended role, which leads to incorrect states being exposed in the Accessibility tree and announced by assistive technologies.
Why is this issue marked as Critical?
Incorrect states and properties break core interaction for assistive technology users across browsers and platforms. Users may receive contradictory or missing feedback, cannot trust control status, and may fail tasks. Because this affects fundamental operability and understanding, it warrants a critical severity.
Are global ARIA attributes always safe to use?
Mostly. Global attributes such as aria-describedby and aria-current are valid on any role. There are two exceptions: naming attributes (aria-label and aria-labelledby) are prohibited on generic elements such as a plain <div> or <span> (see aria-prohibited-attr), and adding a global attribute to an element with role="none" or role="presentation" causes browsers to ignore the presentational role (see presentation-role-conflict).
When is aria-expanded appropriate?
Use aria-expanded only when the control expands or collapses content, or in patterns that require it (such as combobox or a disclosure). Do not place it on roles that do not define expansion behavior.
What if my widget needs attributes that the current role does not allow?
Pick a role that matches the widget’s behavior, or use native HTML elements that already provide the correct semantics and permitted states. Avoid forcing attributes onto roles that do not support them.
What is the difference between aria-allowed-attr and aria-prohibited-attr?
aria-allowed-attr checks whether a role uses only the ARIA attributes explicitly permitted for that role.
aria-prohibited-attr flags attributes that a role explicitly forbids.
Both rules address misuse of ARIA, but from opposite directions:
aria-allowed-attrensures roles only include permitted attributes.aria-prohibited-attrensures roles do not include attributes that the specification forbids.
An attribute can violate one rule or both, depending on how the ARIA specification defines valid and invalid mappings for the role.
Standards and Regulations
| Standard | Success Criterion | Reference |
|---|---|---|
| WCAG 2.2 | 4.1.2 Name, Role, Value (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | 9.4.1.2 Name, Role, Value | Same as the WCAG text. |