Warninga11y.aria-valid

ARIA roles that don't exist or are incomplete

Why it matters

A role tells assistive technology what an element is: role="checkbox" on a <div> makes a screen reader say "checkbox". That is a promise, and a broken one is worse than none. A misspelt or invented role (role="buton", role="dropdown") is ignored, so the element goes back to being an anonymous <div>. A role without the state it depends on is announced and then can't be used: a checkbox with no aria-checked never says whether it is ticked.

The first rule of ARIA is not to use it when HTML already has the element: <button>, <input type="checkbox"> and <select> come with their roles, states and keyboard behaviour built in, and can't get any of this wrong.

We check roles against WAI-ARIA 1.2 and the attributes it marks as required. We don't check that the states are kept up to date by your scripts: that takes a person and a screen reader.

Sources: WCAG 2.2, 4.1.2 Name, Role, Value (Level A); WAI-ARIA 1.2: role definitions; Using ARIA: the first rule.

How to fix it

Best, use the HTML element and delete the role:

<input type="checkbox" id="terms"> <label for="terms">I agree</label>

If it has to be a custom control, give the role what it requires and keep it true from your script:

<div role="checkbox" aria-checked="false" tabindex="0">I agree</div>

Examples

These are the rule's own test pages, and what it says about each. They are run on every change to the rule book.

<div role="widget">Opening hours</div>

Warning1 ARIA role is wrong or unfinished: role="widget" is one the specification keeps for itself (div).

fail-abstract
<div role="buton" tabindex="0">Add to basket</div>

Warning1 ARIA role is wrong or unfinished: role="buton" is not a role (div).

fail-misspelt
<div role="checkbox" tabindex="0">I agree to the terms</div>

Warning1 ARIA role is wrong or unfinished: role="checkbox" needs aria-checked (div).

fail-no-checked
<div role="checkbox" aria-checked="false" tabindex="0">I agree to the terms</div>

PassedEvery ARIA role on the page exists and has the attributes it requires.

pass-complete
<input type="checkbox" role="switch" id="news">
<label for="news">Send me the newsletter</label>

PassedEvery ARIA role on the page exists and has the attributes it requires.

pass-native