How to replace a deprecated ARIA role?

aria-deprecated-role page

The issue

An element with a deprecated ARIA role tells assistive technology to treat it as something the ARIA specification no longer defines. Screen readers may announce it as a plain group, or nothing at all, so a list of links built as a directory loses the structure that made it navigable.

The cause is usually old markup or a component library that hasn’t been updated. The role was valid once and still parses, so nothing on the page looks wrong.

Scope

Each element with an explicit role attribute is checked, unless it or an ancestor is hidden. Probeo treats directory as deprecated; it was deprecated in ARIA 1.2 in favor of list.

How to check you have it

In probeo: the page reports the aria-deprecated-role rule, “Deprecated ARIA roles must not be used”, with minor impact, on each element whose role is deprecated. This is a best practice rather than a WCAG criterion.
By hand: search the page source for role="directory".
With a tool: axe DevTools reports the same rule id.

The fix

Replace the deprecated role with the role that superseded it, or with native HTML.

A directory of links is a list. The simplest fix is to use a <ul> or <ol>, which needs no role at all. If the markup has to stay a <div>, use role="list" on the container and role="listitem" on each entry.

<!-- Before -->
<div role="directory">…</div>

<!-- After -->
<ul>
  <li><a href="/guides/">Guides</a></li>
  <li><a href="/reference/">Reference</a></li>
</ul>

Done when: no element uses a deprecated role, and the check above comes back clean.

Do not

Do not remove the role without giving the content another structure; the list semantics are what made it navigable.
Do not swap one invented or deprecated role for another.

FAQ

Is a deprecated role a WCAG failure?

Not directly. Probeo reports it as a best practice. It becomes a WCAG problem when the content loses structure that people need, such as a list no longer being announced as a list.

Why does probeo only list one deprecated role?

directory is the role ARIA 1.2 deprecated that still turns up in markup. Roles that were never part of ARIA are a different problem, reported by the ARIA attribute rules.

Will browsers stop supporting the role?

A deprecated role may still be mapped by some browsers and screen readers, with no guarantee it is mapped consistently. A native list, or role="list", doesn’t carry that risk.

Which product detects this

Probeo checks this on every page of your site as part of Site Clarity. This page explains one instance; the product tells you every page that has it.