Testing the axe rule aria-allowed-attr

Test cases for the axe-core rule aria-allowed-attr (axe-core 4.14). The rule checks that every ARIA attribute on an element is allowed for that element's role. The role can be explicit (a role attribute) or implicit (the role a native element already has, like link for <a href>).

Under the hood, the rule runs four checks:

Global attributes, like aria-label, aria-describedby, aria-hidden and aria-haspopup, are allowed on any role as far as this rule is concerned.

Every example is live in the page, so you can run the axe extension straight over it. The expected results were checked by running axe-core 4.14.1 over this page. Look in both the axe issues list and the needs review list.

Number of test cases by expected result
Expected resultCases
Fail25
Needs review3
Passes this rule, flagged by a different rule4
Passes, but broken (axe misses it)3
Pass (valid control cases)5
Changes after interaction2

Sections

Not allowed on a native element's role

No role attribute here. Axe works out the implicit role from the element, then checks the attribute against it. A plain <div> has the role generic, which allows only global attributes.

A1 aria-checked on a div

A div trying to be a checkbox without role="checkbox".

Remember me
<div aria-checked="true">Remember me</div>

Expected result: fail

A2 aria-expanded on a div

The disclosure state is on the wrong element. It belongs on the button that controls the panel.

<div aria-expanded="false">Shipping details</div>

Expected result: fail

A3 aria-modal on a div

Missing role="dialog".

Are you sure?
<div aria-modal="true">Are you sure?</div>

Expected result: fail

A4 aria-pressed on a link

Links can't be toggle buttons. Use a <button> instead.

<a href="#a4" aria-pressed="true">Favourite</a>

Expected result: fail

A5 aria-selected on a list item

The listitem role doesn't support selection. That needs role="option" inside a listbox.

  • Medium
<ul>
  <li aria-selected="true">Medium</li>
</ul>

Expected result: fail

A6 aria-required on a button

Buttons can't be required.

<button type="button" aria-required="true">Choose a file</button>

Expected result: fail

A7 aria-readonly on a button

<button type="button" aria-readonly="true">Edit</button>

Expected result: fail

A8 aria-checked on an image

Tick
<img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="Tick" width="20" height="20" aria-checked="true">

Expected result: fail

A9 aria-required on a label

Put aria-required (or better, required) on the input, not the label.

<label for="a9-input" aria-required="true">Email</label>
<input type="email" id="a9-input">

Expected result: fail

A10 aria-sort on a data cell

Only column and row headers can be sorted.

Name
Alex
<table>
  <tr><th>Name</th></tr>
  <tr><td aria-sort="ascending">Alex</td></tr>
</table>

Expected result: fail

A11 aria-sort on a header cell

Control case. A <th> is a column header, which allows aria-sort.

Surname
Nguyen
<table>
  <tr><th aria-sort="ascending">Surname</th></tr>
  <tr><td>Nguyen</td></tr>
</table>

Expected result: pass (valid)

Not allowed on an explicit role

Here the role comes from the role attribute. The attribute has to suit that role.

B1 aria-checked on role="button"

Buttons use aria-pressed for on/off, not aria-checked.

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

Expected result: fail

B2 aria-pressed on role="checkbox"

The opposite mix-up. Checkboxes use aria-checked.

Subscribe
<div role="checkbox" tabindex="0" aria-checked="false" aria-pressed="true">Subscribe</div>

Expected result: fail

B3 aria-selected on role="heading"

Our services
<div role="heading" aria-level="2" aria-selected="true">Our services</div>

Expected result: fail

B4 aria-expanded on role="none"

role="none" removes the element's semantics, so there's nothing left to be expanded.

Menu
<div role="none" aria-expanded="true">Menu</div>

Expected result: fail

B5 Misspelled role

buton isn't a role, so axe falls back to the div's implicit role, generic.

Mute
<div role="buton" tabindex="0" aria-pressed="true">Mute</div>

Expected result: fail

The aria-roles rule also fails this for the invalid role.

B6 Fallback role list

ARIA allows a list of roles, and browsers use the first one they recognise. Here that's switch, which allows both attributes.

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

Expected result: fail

Axe doesn't support fallback role lists, so it treats this as a generic div. In practice browsers would treat it as a switch, so this fail is arguably a false positive.

B7 Same attributes on a single role

Control case. The same markup with just role="switch".

Notifications
<div role="switch" tabindex="0" aria-checked="true" aria-required="true">Notifications</div>

Expected result: pass (valid)

Elements that allow few or no ARIA attributes

Some HTML elements aren't meant to be exposed at all, so they allow few or no ARIA attributes. This is the aria-allowed-attr-elm check.

C1 aria-label on a line break

A <br> only allows aria-hidden.

Level 3
200 George Street

<p>Level 3<br aria-label="new line">200 George Street</p>

Expected result: fail

C2 aria-label on a picture element

A <picture> only allows aria-hidden. The alternative text belongs on the <img>.

Sydney Harbour at dusk
<picture aria-label="Sydney Harbour">
  <img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="Sydney Harbour at dusk" width="40" height="40">
</picture>

Expected result: fail

Things axe ignores on purpose

Axe skips two combinations because they do no harm.

D1 aria-required="false" on a button

Not allowed on a button, but false is the default anyway, so it has no effect. Compare with A6.

<button type="button" aria-required="false">Upload</button>

Expected result: pass (valid)

D2 aria-multiline="false" on contenteditable

A contenteditable region without a role isn't a textbox, but axe lets aria-multiline="false" through.

Type a short note
<div contenteditable="true" aria-multiline="false">Type a short note</div>

Expected result: pass (valid)

D3 aria-multiline="false" without contenteditable

The same attribute on a plain div isn't skipped.

Some text
<div aria-multiline="false">Some text</div>

Expected result: fail

Uppercase values

Some attribute values are case sensitive, and some assistive technologies won't recognise them in uppercase. Axe fails these, unless the lowercase value matches what the attribute falls back to anyway. In that case it's only needs review, because the result is probably the same.

E1 aria-required="TRUE"

If this isn't recognised, aria-required falls back to true, so the result is the same.

<label for="e1-input">Given name</label>
<input type="text" id="e1-input" aria-required="TRUE">

Expected result: needs review

E2 aria-required="FALSE"

If this isn't recognised, it falls back to true, so the field could be announced as required.

<label for="e2-input">Middle name</label>
<input type="text" id="e2-input" aria-required="FALSE">

Expected result: fail

E3 aria-busy="TRUE"

Loading results.
<div aria-busy="TRUE">Loading results.</div>

Expected result: fail

E4 aria-current="Page"

If this isn't recognised, it falls back to true, so it's announced as "current" instead of "current page".

<a href="#e4" aria-current="Page">Home</a>

Expected result: fail

E5 aria-checked="TRUE"

Accept terms
<div role="checkbox" tabindex="0" aria-checked="TRUE">Accept terms</div>

Expected result: fail

E6 aria-checked="Mixed"

Select all
<div role="checkbox" tabindex="0" aria-checked="Mixed">Select all</div>

Expected result: fail

E7 Lowercase values

Control case.

Select all toppings
<div role="checkbox" tabindex="0" aria-checked="mixed">Select all toppings</div>

Expected result: pass (valid)

Needs review for other reasons

Two more situations where axe isn't sure.

F1 Deprecated aria-grabbed

aria-grabbed and aria-dropeffect were deprecated in ARIA 1.1. This is the aria-no-deprecated-attr check.

Drag me
<div aria-grabbed="false">Drag me</div>

Expected result: needs review

F2 aria-pressed on a custom element

Axe can't tell what a custom element is, so it asks you to check that nothing breaks if the attribute is ignored.

Shuffle
<fancy-toggle aria-pressed="true">Shuffle</fancy-toggle>

Expected result: needs review

F3 The same custom element, made focusable

Once it has tabindex, axe treats it as an interactive element with no role, and fails it.

Repeat
<fancy-toggle tabindex="0" aria-pressed="true">Repeat</fancy-toggle>

Expected result: fail

Passes this rule, but another rule flags it

These are allowed as far as aria-allowed-attr is concerned, but a different axe rule picks them up. Worth knowing when you're reading a report.

G1 aria-label on a paragraph

aria-label is global, so this rule allows it. But the paragraph role prohibits naming, so most screen readers ignore it.

Applications close on Friday.

<p aria-label="Important">Applications close on Friday.</p>

Expected result: passes this rule, flagged by aria-prohibited-attr

G2 aria-label on a span

Same again, with the generic role.

$25
<span aria-label="Price">$25</span>

Expected result: passes this rule, flagged by aria-prohibited-attr

G3 role="none" on a button

Because the button is focusable, browsers ignore role="none", so it stays a button and aria-pressed is allowed.

<button type="button" role="none" aria-pressed="false">Like</button>

Expected result: passes this rule, flagged by presentation-role-conflict

G4 aria-checked that contradicts a native checkbox

Allowed on a checkbox, but it says checked when the checkbox isn't.

<input type="checkbox" id="g4-input" aria-checked="true">
<label for="g4-input">Send me updates</label>

Expected result: passes this rule, flagged by aria-conditional-attr

Allowed, but wrong

This rule checks that the attribute is allowed on the role, not that it's true. None of these are flagged by any axe rule.

H1 aria-haspopup on a paragraph

aria-haspopup is global, so it's allowed anywhere. But nothing pops up, and a paragraph can't be activated.

Opening hours

<p aria-haspopup="true">Opening hours</p>

Expected result: passes, but it's broken (check manually)

H2 aria-multiline on a single line input

Allowed on a textbox, but an <input> can only ever hold one line.

<label for="h2-input">Comments</label>
<input type="text" id="h2-input" aria-multiline="true">

Expected result: passes, but it's broken (check manually)

H3 aria-readonly on an editable input

Announced as read only, but you can still type in it.

<label for="h3-input">Company name</label>
<input type="text" id="h3-input" aria-readonly="true">

Expected result: passes, but it's broken (check manually)

Changes after interaction

Axe only sees the page as it is when you run it. These pass on page load. Activate each button, then run axe again.

I1 Tabs that add aria-selected to plain buttons

The script marks the clicked button as selected, but the buttons don't have role="tab", so aria-selected isn't allowed on them.

<div>
  <button type="button" class="i1-tab">Monthly</button>
  <button type="button" class="i1-tab">Yearly</button>
</div>

On load: pass. After clicking a button: fail

I2 Toggle that uses aria-checked instead of aria-pressed

The script toggles aria-checked on a button. A button should use aria-pressed.

<button type="button" id="i2-button">Captions</button>

On load: pass. After clicking: fail