# Deprecated ARIA roles must not be used

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/axe/4.11/aria-deprecated-role
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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](https://www.w3.org/TR/wai-aria/).

## Examples

### Incorrect: Using the Deprecated `directory` Role

```html
<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:

```html
<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:

```html
<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:

```html
<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.