Avoid deprecated ARIA roles

WCAG 4.1.2
Name, Role, Value

Content available in English only.

Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).

These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.

Deprecated ARIA roles break accessibility; always use current roles or semantic HTML.

Why this matters and how to fix it

Why this matters

Deprecated ARIA roles are no longer recognized by modern assistive technologies. Using them can cause screen readers to ignore elements or announce them incorrectly, breaking navigation or interactive functionality.

How to fix this issue

Replace deprecated roles with their current WAI-ARIA 1.2 equivalents or use semantic HTML elements that provide the same meaning. Always verify that the new role accurately reflects the element’s purpose.

Automated detection · Manual review recommended

Developer guidance

Legacy components may contain deprecated roles. Use the GetWCAG automated scanner to detect them and replace any deprecated roles with valid ones or semantic HTML elements.

Code examples

Incorrect Implementation

<div role="directory"></div>

Correct Implementation

<nav aria-label="Site sections"></nav>

Real-World Examples

Before

<div role="directory">Menu</div> <!-- Screen reader may ignore or announce incorrectly -->

After

<nav aria-label="Site sections">Menu</nav> <!-- Screen reader announces correctly with proper landmark role -->

Manual testing

  1. 1. Scan code for deprecated ARIA roles (for example, directory, command, dialogbox).
  2. 2. Replace with valid roles or semantic HTML equivalents.
  3. 3. Test with a screen reader (NVDA, JAWS, or VoiceOver) to confirm correct announcement.
  4. 4. Run a scan with the GetWCAG automated scanner to confirm no deprecated roles remain.
  5. 5. Document any role updates in the component library.
eu icon getwcag

Trusted by organizations across Europe working toward WCAG and EAA conformance