Invalid ARIA role values and how to check them
A misspelled or invented role gives an element no semantics at all. squirrel validates every role attribute against the ARIA vocabulary.
What a valid role is
WAI-ARIA defines a closed vocabulary of role names. A value outside it is discarded: the element keeps whatever semantics its tag already had, and the intended role never reaches assistive technology. Nothing warns you, which is what makes a typo such as role="buton" expensive.
The role attribute accepts a whitespace-separated fallback chain, and a browser uses the first token it recognizes. That makes role="doc-subtitle heading" legitimate markup even though only the second token is core ARIA.
What squirrel checks
One check, aria-roles, at severity error. It reads every [role] element, trims the value, splits it on whitespace, lowercases each token and looks it up in a set of 83 role names covering document structure, widgets, composite widgets, landmarks, live regions and window roles.
- Fail with
N invalid ARIA role(s) found. Items readdiv: role="buton", up to ten with a count of the rest. - Pass with
N element(s) with valid ARIA roles. - Info with
No ARIA roles found.
Two limits are worth knowing. Every token in a fallback chain is validated, so role="doc-subtitle heading" is reported even though the chain is written correctly: a browser that supports doc-subtitle uses it, and one that does not falls through to heading. And the vocabulary is core ARIA only, so the DPUB-ARIA and Graphics-ARIA module roles are all reported as invalid.
How to fix it
<div role="button" tabindex="0">Save</div>Fix the spelling, or drop the attribute. A native <button> needs no role at all, and replacing the <div> removes this finding along with the keyboard handling you would otherwise have to write.
squirrel lowercases each token before comparing, so role="BUTTON" is accepted here. Write roles in lowercase anyway: the ARIA specification defines them that way.
| Rule ID | a11y/aria-roles |
| Category | Accessibility |
| Scope | Per-page |
| Severity | error |
| Weight | 8/10 |
Enable / disable
Disable this rule
[rules]
disable = ["a11y/aria-roles"]Disable all Accessibility rules
[rules]
disable = ["a11y/*"]Enable only this rule
[rules]
enable = ["a11y/aria-roles"]enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.
Related rules
- a11y/aria-deprecated-role: roles that exist but should not be used.
- a11y/aria-valid-attr: the same problem in
aria-*attribute names. - a11y/aria-required-attr: the attributes a valid role then has to declare.
- a11y/aria-allowed-attr: attributes that contradict the role you chose.
Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.
References
Check your site
Run squirrel audit https://example.com and open the Accessibility section of the report. Each unrecognized role is listed with the element carrying it. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.