aria-allowed-attr
aria-* attributes must be permitted for the element’s role
Checks that every recognized aria-* attribute present on an element with an explicit role is either globally supported or supported by that role.
Applies to. Applies to elements carrying at least one recognized, non-global aria-* attribute, judged against the role they actually have: an explicit valid role, else the implicit role of their tag, else, for the elements HTML-AAM maps to no role at all, nothing. A custom element with no role attribute naming a role is judged against the role its ElementInternals give it (this.attachInternals().role), its default role, as a native element is judged against its tag's.
Expectation. Every recognized aria-* attribute present is either: (a) globally supported on any element (the "global" ARIA states/properties, e.g. aria-label/aria-hidden/aria-describedby), or (b) explicitly listed as a required or supported state/property for the element's role. An attribute ARIA deprecated (rather than prohibited) on the role is still allowed: it is reported as CANTTELL, so the author decides, not as a not-allowed FAIL. The same goes for an element with no role: an attribute ARIA 1.2 made no longer global (aria-disabled, aria-errormessage, aria-haspopup, aria-invalid) is CANTTELL there too. An attribute the role does not support is reported at CANTTELL as well, not FAIL. It is a WAI-ARIA violation, but the element keeps the name, role and state it has without the attribute: <button aria-valuenow="1">Save</button> is still a button named Save. ACT 5c01ea maps this to WAI-ARIA, and to SC 1.3.1 and 4.1.2 only as secondary requirements "less strict" than the rule. Whether SC 4.1.2 fails depends on whether the element is a control whose state or value the page meant the attribute to convey and conveys no other way (a toggle button given aria-checked instead of aria-pressed); a person settles that.
What a finding reports.
attr: the aria-* attribute that is not allowed, or deprecated, on the element.role(an element with a role): the role it was judged against, explicit or implicit. Absent when the element has no role at all.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<div role="checkbox" aria-checked="true"></div>
aria-checked is one of the states role="checkbox" supports.
<div role="checkbox" aria-valuenow="1"></div>
aria-valuenow belongs to range widgets, not role="checkbox": a WAI-ARIA violation. The checkbox keeps its name, role and state without it, so whether WCAG 4.1.2 fails depends on what the attribute was meant to convey.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
ARIA_ATTR_DEPRECATED
- Inspect the element the report names and note the deprecated aria-* attribute and the element's role.
- Open the Accessibility pane in the browser's developer tools and check whether the attribute's state still shows on the element (for example disabled, invalid, has popup).
- With a screen reader, move to the element and listen for that state being announced.
- Look for a non-deprecated way to convey the same thing (a native attribute such as disabled, or a role that supports the attribute) and whether the page already uses it.
Pass. The state is announced, or it is also conveyed by a native attribute or a supported role, so nothing depends on the deprecated attribute alone.
Fail. The state is conveyed only by the deprecated attribute and the screen reader does not announce it, so the element's state is not exposed (WCAG 4.1.2).
ARIA_ATTR_NOT_ALLOWED
- Inspect the element the report names and note the attribute and the element's role.
- Work out what the attribute was meant to convey, such as a checked, pressed or selected state, or a value.
- Check whether the element is a control and whether that state or value is conveyed some other way its role supports, such as aria-pressed on a button or the native control's own state.
Pass. The attribute conveys nothing the element needs, or the same state or value is conveyed a supported way. Still remove it: WAI-ARIA does not allow it on this role.
Fail. The element is a control whose state or value is conveyed only by this attribute, which its role does not support, so that state or value is not exposed (WCAG 4.1.2).
ARIA_ATTR_NOT_ALLOWED_ROLELESS
- Inspect the element the report names, which has no role, and note the attribute.
- Check whether the element works as a control: it takes focus or responds to clicks or keys.
- If it does, check whether the state or value the attribute was meant to convey is conveyed any other way.
Pass. The element is not a control, or its state or value is conveyed another way. Still remove the attribute: nothing supports it on an element with no role.
Fail. The element works as a control and conveys its state or value only through this attribute, which nothing supports on an element with no role (WCAG 4.1.2).