Testing the axe rule aria-valid-attr-value
Test cases for the axe-core rule aria-valid-attr-value (external site) (axe-core 4.14). Every example below 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, because several missing ID cases only show up in needs review.
| Expected result | Cases |
|---|---|
| Fail | 31 |
| Needs review | 12 |
| Pass, but broken (axe misses it) | 5 |
| Pass (valid control cases) | 5 |
| Changes after interaction | 2 |
What this page shows
The axe-core rule aria-valid-attr-value checks that the value of an ARIA attribute is allowed. It does not check whether the attribute suits the element. This page has 55 live examples, so you can run axe over them and compare what it reports with what the examples actually do.
The examples fall into five groups. Each group tells you something different about what an automated check can and cannot find.
Fail (31 examples)
Axe reports a failure when a value is clearly invalid. There are three common causes:
- The wrong type of value. For example, words where a number is needed (
aria-level="two",aria-valuenow="50%"),"yes"or a misspelling wheretrueorfalseis needed, or a keyword that does not exist (aria-live="rude",aria-sort="asc"). - A missing ID on the attributes axe checks strictly. These are
aria-activedescendant,aria-owns,aria-details,aria-flowto, andaria-controlswhen the control is expanded. - A broken
aria-errormessage. It lists more than one ID, points to a hidden element, or points to a plain paragraph.
Needs review (12 examples)
Axe cannot be certain, so it asks a person to check. These results appear in the needs review list, not the issues list, so they are easy to miss. They include:
- A missing ID on
aria-labelledbyoraria-describedby. The target element may be added later. Typos, the wrong case, a leading#and comma-separated IDs all end up here. aria-controlstogether witharia-haspopup. The popup may live elsewhere in the page.- Values that browsers tolerate, such as an unknown
aria-currentvalue, or anaria-levelabove 6. - Empty values, such as
aria-expanded="",aria-hidden=""andaria-valuenow="".
Pass, but broken (5 examples)
These examples have real problems that axe passes. They show why a clean result does not mean the markup is correct:
- A list where one ID is valid. Axe only needs one of the IDs to exist, so the missing part of a name or a control is silently lost.
- Collapsed controls. Axe skips a missing
aria-controlsoraria-ownstarget whenaria-expanded="false", because many scripts only add the panel when it opens. - A problem waiting to happen. A missing
aria-errormessageID is ignored whilearia-invalid="false", but it breaks as soon as a script marks the field invalid.
Pass, valid control cases (5 examples)
These are correct examples that should pass. They confirm that the rule does not flag everything. They include an ID that exists, aria-required="TRUE" (the case of a true or false value does not matter), aria-setsize="-1" (allowed, and means the total is unknown), an empty aria-labelledby (allowed), and a correctly built aria-errormessage.
Changes after interaction (2 examples)
Both examples pass when the page loads and fail after you use them. One toggle button writes aria-pressed="null". One disclosure button builds its panel with a typo in the ID. Axe only tests the page as it is at the moment you run it, so open, press and toggle things, then run axe again.
The takeaway
Axe is good at catching clearly invalid values. It is honest about the cases it cannot judge, and it cannot see problems that only exist in a collapsed, partial or later state. Automated results are a starting point, and manual testing is still needed.
Result code
Every example has a coloured box showing the expected axe result:
Expected axe result: fail. Axe reports it in the issues list.
Expected axe result: needs review. Axe reports it in the needs review list.
Expected axe result: pass, but it's broken. Axe misses it, so check manually.
Expected axe result: pass (valid). A control case.
Expected axe result: pass on load, fail after interaction. Activate the control, then run axe again.
Single ID references
These attributes take exactly one ID. If the ID doesn't exist, axe fails it outright.
Example A1: aria-activedescendant points to a missing ID
The listbox says the active option is a1-apple, but the only option has the ID a1-banana.
Expected axe result: fail.
HTML markup
<div role="listbox" tabindex="0" aria-label="Fruit" aria-activedescendant="a1-apple">
<div role="option" id="a1-banana">Banana</div>
</div>
Example A2: aria-activedescendant points to a real ID
Control case. The ID exists, so this passes.
Expected axe result: pass (valid).
HTML markup
<div role="listbox" tabindex="0" aria-label="Vegetables" aria-activedescendant="a2-carrot">
<div role="option" id="a2-carrot">Carrot</div>
</div>
ID reference lists
These attributes can take a space separated list of IDs. Axe only needs one of the IDs to exist, and it treats some attributes more gently than others.
Example B1: aria-labelledby points to a missing ID
The button is labelled by b1-label, which doesn't exist.
Expected axe result: needs review. Axe doesn't fail missing aria-labelledby IDs. It reports them as needs review.
HTML markup
<button type="button" aria-labelledby="b1-label">Save</button>
Example B2: aria-labelledby with two IDs, one missing
The first ID exists, the second doesn't.
Expected axe result: pass, but it's broken. Check manually. Axe passes this because at least one ID exists. The second part of the name is silently lost.
HTML markup
<span id="b2-first">Delivery</span>
<input type="text" aria-labelledby="b2-first b2-second">
Example B3: aria-describedby ID has a typo
The input points to b3-hint but the hint has the ID b3-hints.
Expected axe result: needs review. Like aria-labelledby, a missing aria-describedby ID is needs review, not a fail.
Four digits, for example 2000.
HTML markup
<label for="b3-input">Postcode</label>
<input type="text" id="b3-input" aria-describedby="b3-hint">
<p id="b3-hints">Four digits, for example 2000.</p>
Example B4: aria-describedby ID uses the wrong case
The input points to b4-Hint but the hint has the ID b4-hint. IDs are case sensitive.
Expected axe result: needs review.
Include the area code.
HTML markup
<label for="b4-input">Phone</label>
<input type="tel" id="b4-input" aria-describedby="b4-Hint">
<p id="b4-hint">Include the area code.</p>
Example B5: aria-describedby ID starts with a hash
Someone has written the ID like a CSS selector or link: #b5-hint.
Expected axe result: needs review.
We will never share your email.
HTML markup
<label for="b5-input">Email</label>
<input type="email" id="b5-input" aria-describedby="#b5-hint">
<p id="b5-hint">We will never share your email.</p>
Example B6: aria-describedby IDs separated by a comma
The list should be space separated. With a comma, the browser looks for a single ID called b6-hint,b6-error.
Expected axe result: needs review.
At least 12 characters.
Password is too short.
HTML markup
<label for="b6-input">Password</label>
<input type="password" id="b6-input" aria-describedby="b6-hint,b6-error">
<p id="b6-hint">At least 12 characters.</p>
<p id="b6-error">Password is too short.</p>
Example B7: aria-controls points to a missing ID (expanded)
The button says it's expanded and controls b7-panel, which doesn't exist.
Expected axe result: fail.
HTML markup
<button type="button" aria-expanded="true" aria-controls="b7-panel">Filters</button>
Example B8: aria-controls points to a missing ID (collapsed)
Same as above, but aria-expanded="false".
Expected axe result: pass, but it's broken. Check manually. Axe deliberately skips this, because many scripts only add the panel to the DOM when it opens. Open it and check again.
HTML markup
<button type="button" aria-expanded="false" aria-controls="b8-panel">Sort options</button>
Example B9: aria-controls points to a missing ID with aria-haspopup
A menu button controlling b9-menu, which doesn't exist.
Expected axe result: needs review. With aria-haspopup set, axe assumes the popup may live elsewhere and asks you to check.
HTML markup
<button type="button" aria-haspopup="menu" aria-expanded="true" aria-controls="b9-menu">Account</button>
Example B10: aria-controls with two IDs, one missing
The first panel exists, the second doesn't.
Expected axe result: pass, but it's broken. Check manually. One valid ID is enough for axe to pass it.
HTML markup
<button type="button" aria-expanded="true" aria-controls="b10-panel-1 b10-panel-2">Show all</button>
<div id="b10-panel-1">Panel one content.</div>
Example B11: aria-owns points to a missing ID
The list says it owns b11-item, which doesn't exist.
Expected axe result: fail.
- First item
HTML markup
<ul aria-owns="b11-item">
<li>First item</li>
</ul>
Example B12: aria-owns points to a missing ID (collapsed)
A collapsed combobox that owns a listbox that doesn't exist yet.
Expected axe result: pass, but it's broken. Check manually. As with aria-controls, axe skips aria-owns when aria-expanded="false".
HTML markup
<input type="text" role="combobox" aria-label="City" aria-expanded="false" aria-owns="b12-list">
Example B13: aria-details points to a missing ID
The image points to a longer description that doesn't exist.
Expected axe result: fail.
HTML markup
<img src="data:image/gif;base64,R0lGODlhAQABAAAAACw=" alt="Sales chart" aria-details="b13-details" width="40" height="40">
Example B14: aria-flowto points to a missing ID
The section says reading should continue at b14-next, which doesn't exist.
Expected axe result: fail.
HTML markup
<div aria-flowto="b14-next">Read this first.</div>
aria-errormessage
Axe checks aria-errormessage separately, and only when aria-invalid is set to something other than false.
Example C1: aria-errormessage points to a missing ID
The field is invalid and points to c1-error, which doesn't exist.
Expected axe result: needs review.
HTML markup
<label for="c1-input">Name</label>
<input type="text" id="c1-input" aria-invalid="true" aria-errormessage="c1-error">
Example C2: aria-errormessage with two IDs
aria-errormessage only allows one ID.
Expected axe result: fail.
Enter a suburb.
Suburb not found.
HTML markup
<label for="c2-input">Suburb</label>
<input type="text" id="c2-input" aria-invalid="true" aria-errormessage="c2-error-1 c2-error-2">
<p id="c2-error-1" role="alert">Enter a suburb.</p>
<p id="c2-error-2" role="alert">Suburb not found.</p>
Example C3: aria-errormessage points to a hidden element
The error message exists but is hidden with the hidden attribute.
Expected axe result: fail.
Enter a number.
HTML markup
<label for="c3-input">Age</label>
<input type="text" id="c3-input" aria-invalid="true" aria-errormessage="c3-error">
<p id="c3-error" role="alert" hidden>Enter a number.</p>
Example C4: aria-errormessage points to a plain paragraph
The error exists and is visible, but it isn't a live region and isn't also referenced by aria-describedby.
Expected axe result: fail.
Choose a state.
HTML markup
<label for="c4-input">State</label>
<input type="text" id="c4-input" aria-invalid="true" aria-errormessage="c4-error">
<p id="c4-error">Choose a state.</p>
Example C5: Missing aria-errormessage ID, but aria-invalid="false"
The ID doesn't exist, but the field isn't invalid, so axe doesn't check it.
Expected axe result: pass, but it's broken. Check manually. This will break as soon as a script flips aria-invalid to true.
HTML markup
<label for="c5-input">Country</label>
<input type="text" id="c5-input" aria-invalid="false" aria-errormessage="c5-error">
Example C6: aria-errormessage done right
Control case. One ID, visible, and a live region.
Expected axe result: pass (valid).
Enter a town.
HTML markup
<label for="c6-input">Town</label>
<input type="text" id="c6-input" aria-invalid="true" aria-errormessage="c6-error">
<p id="c6-error" role="alert">Enter a town.</p>
True/false values
These attributes only accept true or false (some also accept undefined). Axe ignores case, so TRUE is fine.
Example D1: aria-hidden misspelled
Expected axe result: fail.
Decorative text.
HTML markup
<p aria-hidden="rtue">Decorative text.</p>
Example D2: aria-required="required"
A very common mix-up with the HTML required attribute.
Expected axe result: fail.
HTML markup
<label for="d2-input">Surname</label>
<input type="text" id="d2-input" aria-required="required">
Example D3: aria-disabled="disabled"
Same mix-up, this time with the HTML disabled attribute.
Expected axe result: fail.
HTML markup
<button type="button" aria-disabled="disabled">Submit</button>
Example D4: aria-busy="1"
Numbers aren't allowed in place of true/false.
Expected axe result: fail.
HTML markup
<div aria-busy="1">Loading results.</div>
Example D5: aria-modal="yes"
Expected axe result: fail.
HTML markup
<div role="dialog" aria-label="Confirm" aria-modal="yes">Are you sure?</div>
Example D6: aria-required="TRUE"
Control case. Uppercase is allowed.
Expected axe result: pass (valid).
HTML markup
<label for="d6-input">Given name</label>
<input type="text" id="d6-input" aria-required="TRUE">
Token values
These attributes accept a fixed list of keywords. Anything else is invalid.
Example E1: aria-checked="checked"
Allowed values are true, false and mixed.
Expected axe result: fail.
HTML markup
<div role="checkbox" tabindex="0" aria-checked="checked">Subscribe</div>
Example E2: aria-pressed="on"
Expected axe result: fail.
HTML markup
<button type="button" aria-pressed="on">Bold</button>
Example E3: aria-expanded="open"
Expected axe result: fail.
HTML markup
<button type="button" aria-expanded="open">Menu</button>
Example E4: aria-selected="yes"
Expected axe result: fail.
HTML markup
<div role="tablist" aria-label="Plans">
<button type="button" role="tab" aria-selected="yes">Monthly</button>
</div>
Example E5: aria-current="yes"
Allowed values are page, step, location, date, time, true and false.
Expected axe result: needs review. Axe only flags invalid aria-current values as needs review, because browsers treat unknown values as true.
HTML markup
<a href="#e5" aria-current="yes">Home</a>
Example E6: aria-live="rude"
rude was dropped from ARIA long ago.
Expected axe result: fail.
HTML markup
<div aria-live="rude">Status messages.</div>
Example E7: aria-autocomplete="on"
Another mix-up with the HTML attribute. Allowed values are inline, list, both and none.
Expected axe result: fail.
HTML markup
<input type="text" role="combobox" aria-label="Search" aria-expanded="false" aria-autocomplete="on">
Example E8: aria-haspopup="popup"
Expected axe result: fail.
HTML markup
<button type="button" aria-haspopup="popup">Options</button>
Example E9: aria-sort="asc"
It must be the full word, ascending.
Expected axe result: fail.
| Name |
|---|
| Alex |
HTML markup
<table>
<tr><th aria-sort="asc">Name</th></tr>
<tr><td>Alex</td></tr>
</table>
Example E10: aria-invalid="error"
Expected axe result: fail.
HTML markup
<label for="e10-input">Code</label>
<input type="text" id="e10-input" aria-invalid="error">
Example E11: aria-orientation="landscape"
Expected axe result: fail.
HTML markup
<div role="separator" aria-orientation="landscape"></div>
Example E12: aria-relevant with one bad token
additions is fine, removed isn't (it should be removals).
Expected axe result: fail.
HTML markup
<div aria-live="polite" aria-relevant="additions removed">Chat log.</div>
Number values
Some attributes need a whole number (with a minimum), others any number. Units and words aren't allowed.
Example F1: aria-level="two"
Expected axe result: fail.
HTML markup
<div role="heading" aria-level="two">Contact us</div>
Example F2: aria-level="0"
The lowest allowed level is 1.
Expected axe result: fail.
HTML markup
<div role="heading" aria-level="0">About us</div>
Example F3: aria-level="7"
Valid in ARIA, but some screen readers don't support heading levels above 6.
Expected axe result: needs review.
HTML markup
<div role="heading" aria-level="7">Fine print</div>
Example F4: aria-valuenow="fifty"
Expected axe result: fail.
HTML markup
<div role="slider" tabindex="0" aria-label="Volume" aria-valuemin="0" aria-valuemax="100" aria-valuenow="fifty"></div>
Example F5: aria-valuenow="50%"
Use aria-valuetext if you want to add units.
Expected axe result: fail.
HTML markup
<div role="progressbar" aria-label="Upload" aria-valuenow="50%"></div>
Example F6: aria-valuemin="0,5"
A comma as a decimal separator isn't allowed.
Expected axe result: fail.
HTML markup
<div role="slider" tabindex="0" aria-label="Zoom" aria-valuemin="0,5" aria-valuemax="3" aria-valuenow="1"></div>
Example F7: aria-posinset="0"
Positions start at 1.
Expected axe result: fail.
HTML markup
<div role="listbox" aria-label="Sizes">
<div role="option" aria-selected="false" aria-posinset="0" aria-setsize="3">Small</div>
</div>
Example F8: aria-colindex="1.5"
Must be a whole number.
Expected axe result: fail.
HTML markup
<div role="grid" aria-label="Scores">
<div role="row">
<div role="gridcell" aria-colindex="1.5">10</div>
</div>
</div>
Example F9: aria-setsize="-1"
Control case. -1 is allowed and means the total is unknown.
Expected axe result: pass (valid).
HTML markup
<div role="listbox" aria-label="Results">
<div role="option" aria-selected="false" aria-posinset="1" aria-setsize="-1">Result one</div>
</div>
Empty values
An empty value is fine for text and ID attributes, but not for true/false, token or number attributes.
Example G1: aria-expanded=""
Expected axe result: needs review. Axe reports empty non-text values as needs review rather than a fail.
HTML markup
<button type="button" aria-expanded="">More</button>
Example G2: aria-hidden=""
Expected axe result: needs review.
Some text.
HTML markup
<p aria-hidden="">Some text.</p>
Example G3: aria-valuenow=""
Expected axe result: needs review.
HTML markup
<div role="progressbar" aria-label="Download" aria-valuenow=""></div>
Example G4: aria-labelledby=""
An empty ID list is allowed, so this rule passes it. The button still has its text as a name.
Expected axe result: pass (valid).
HTML markup
<button type="button" aria-labelledby="">Print</button>
Changes after interaction
Axe only sees the page as it is when you run it. Both of these pass on page load. Activate each button, then run axe again.
Example H1: Toggle writes aria-pressed="null"
The script reads the state from a variable that is never set, so after the first press aria-pressed becomes the text null.
Expected axe result: pass on load, fail after pressing.
HTML markup
<button type="button" id="h1-button" aria-pressed="false">Italic</button>
JavaScript
var pressedState;
document.getElementById('h1-button').addEventListener('click', function () {
var current = this.getAttribute('aria-pressed') === 'true';
pressedState = current ? 'false' : null; // bug: should be 'true'
this.setAttribute('aria-pressed', String(pressedState));
});
Example H2: Panel is added with the wrong ID
The button starts collapsed, so axe skips the missing aria-controls target. When opened, the script adds the panel with the ID h2-pannel (typo) instead of h2-panel.
Expected axe result: pass on load, fail after opening.
HTML markup
<button type="button" id="h2-button" aria-expanded="false" aria-controls="h2-panel">Shipping details</button>
<div id="h2-container"></div>
JavaScript
document.getElementById('h2-button').addEventListener('click', function () {
var container = document.getElementById('h2-container');
var isOpen = this.getAttribute('aria-expanded') === 'true';
if (isOpen) {
this.setAttribute('aria-expanded', 'false');
container.innerHTML = '';
} else {
this.setAttribute('aria-expanded', 'true');
container.innerHTML = '<div id="h2-pannel"><p>Standard shipping takes 3 to 5 days.</p></div>';
}
});