Deprecated and abstract ARIA roles, and what to use instead

What a deprecated or abstract role is

WAI-ARIA marks a role deprecated when it has been superseded. directory is the current example: ARIA 1.2 deprecates it in favor of list.

Abstract roles are a separate problem. The specification uses them to organize the role taxonomy, and states that they must not be used in content. command, composite, input, landmark, range, roletype, section, sectionhead, select, structure, widget and window all exist only as base types for the concrete roles that extend them. An element carrying one gets no semantics from it.

What squirrel checks

One check, aria-deprecated-role, at severity error. It reads every role attribute, lowercases it, splits it on whitespace to handle fallback chains, and looks each token up in its list of the deprecated directory role plus the twelve abstract roles.

• Fail when any token matches. Report message: N deprecated/abstract role(s) found. Each item names the element, the role and the replacement, for example ul[role="directory"]: Use 'list' instead or div[role="widget"]: Abstract role - use specific widget types. Up to ten items are shown with a count of the rest.
• Pass with No deprecated ARIA roles found when the page uses roles but none match.
• Info with No ARIA roles found.

How to fix it

<ul role="list">
  <li>Ada Lovelace</li>
  <li>Grace Hopper</li>
</ul>

Replace the role with the concrete one the message names. For an abstract role, pick the specific descendant that matches what the element does: button or link rather than command, slider or progressbar rather than range, dialog rather than window.

Removing the attribute is often better than replacing it. A <ul> already has an implicit list role, so role="list" is only needed where CSS such as list-style: none has stripped the semantics in Safari.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/aria-deprecated-role"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/aria-deprecated-role"]

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-roles: role values that are not in the vocabulary at all.
• a11y/aria-required-children: roles that need particular children once you switch to a concrete one.
• a11y/aria-required-parent: the same relationship seen from the child.
• a11y/list-structure: native lists carrying elements they should not.

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

• Abstract roles, WAI-ARIA 1.2
• directory role, WAI-ARIA 1.2
• ARIA roles, MDN

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Each offending role is listed with the element and its recommended replacement. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.