Deprecated ARIA roles must not be used

The WAI-ARIA specification evolves over time. As it matures, certain roles are deprecated because they were found to be redundant, poorly supported, or better served by other mechanisms. When you use a deprecated role, you’re relying on semantics that assistive technologies are no longer expected to support. This means the role may be completely ignored, misinterpreted, or cause unexpected behavior.

Users most affected include:

• Blind and deafblind users who rely on screen readers to convey the purpose and structure of elements on a page.
• Users with mobility impairments who depend on assistive technologies that use ARIA roles for navigation and interaction.

When a screen reader encounters an element with a deprecated role, it may announce it generically (e.g., as a simple group or section) or skip the role announcement entirely. This strips away meaningful context that helps users understand the content structure and interact with it effectively.

Relevant WCAG Success Criteria

This rule relates to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A). This criterion requires that for all user interface components, the name, role, and value can be programmatically determined and that changes to these are available to assistive technologies. Using a deprecated role means the role cannot be reliably determined, which violates this requirement.

This applies across WCAG 2.0, 2.1, and 2.2 at Level A, as well as EN 301 549 (guideline 9.4.1.2).

How to Fix It

1. Identify deprecated roles in your codebase. The axe-core rule checks all elements with a role attribute against the current WAI-ARIA specification.
2. Replace deprecated roles with supported alternatives. Currently, the primary deprecated role flagged is:
   • directory: Replace with list, tree, or section depending on the content structure. If the directory represents a flat list of items (like a table of contents), use list. If it represents a hierarchical, expandable structure, use tree. If it’s a general grouping of related content, use section.
3. Test with assistive technologies after making changes to confirm the new role conveys the intended meaning.

As the WAI-ARIA specification continues to evolve, additional roles may be deprecated in future versions. Keep your ARIA usage up to date by referencing the latest WAI-ARIA specification.

Examples

Incorrect: Using the Deprecated directory Role

<div role="directory">
  <ul>
    <li><a href="#section-1">Section 1</a></li>
    <li><a href="#section-2">Section 2</a></li>
    <li><a href="#section-3">Section 3</a></li>
  </ul>
</div>

The directory role is deprecated. Assistive technologies may not recognize it, leaving users without useful semantic information about this element.

Correct: Using a Supported Role Instead

If the content is a simple list of links (such as a table of contents), use list or rely on the native <ul> semantics:

<nav aria-label="Table of contents">
  <ul>
    <li><a href="#section-1">Section 1</a></li>
    <li><a href="#section-2">Section 2</a></li>
    <li><a href="#section-3">Section 3</a></li>
  </ul>
</nav>

In this example, the native <ul> element already provides the list role, and wrapping it in a <nav> with an aria-label gives assistive technology users clear context about its purpose.

Correct: Using tree for Hierarchical Content

If the content represents an expandable, nested structure, use the tree role with appropriate child roles:

<ul role="tree" aria-label="Site map">
  <li role="treeitem" aria-expanded="true">
    Section 1
    <ul role="group">
      <li role="treeitem">Subsection 1.1</li>
      <li role="treeitem">Subsection 1.2</li>
    </ul>
  </li>
  <li role="treeitem">Section 2</li>
</ul>

Correct: Using section for a General Content Grouping

If the deprecated directory role was used simply to group related content, a <section> element with an accessible name is a good replacement:

<section aria-label="Staff directory">
  <ul>
    <li>Alex Johnson — Engineering</li>
    <li>Maria Garcia — Design</li>
    <li>Sam Lee — Marketing</li>
  </ul>
</section>

The key is to choose a replacement that accurately reflects the structure and purpose of the content, ensuring assistive technologies can convey it meaningfully to users.

Learn more:

Deque Reference

Deque University - How To Fix

→