ARIA roles used must conform to valid values

When you assign a role attribute to an HTML element, you are explicitly telling browsers and assistive technologies what that element represents and how users should interact with it. If the value is misspelled, invented, or references an abstract role (like widget, roletype, landmark, or structure), the browser cannot map the element to any known role. The result is that assistive technologies either ignore the role entirely or fall back to the element’s native semantics, which may not reflect your intent.

This is a critical accessibility problem. Users who rely on screen readers — including people who are blind, deafblind, or have mobility impairments — depend on accurate role information to navigate and interact with a page. A button announced as a generic element, or a navigation landmark that isn’t recognized at all, can make an interface confusing or completely unusable.

This rule relates to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that the role of every user interface component can be programmatically determined. It applies across WCAG 2.0, 2.1, and 2.2, as well as EN 301 549 (Section 9.4.1.2).

How to Fix

1. Check spelling. The most common cause of invalid roles is a simple typo, such as role="buton" instead of role="button".
2. Use only defined roles. Every value must correspond to an actual role in the WAI-ARIA specification.
3. Never use abstract roles. Abstract roles like widget, roletype, landmark, structure, input, range, section, sectionhead, select, command, and composite exist only as conceptual categories in the spec. They must not be used in markup.
4. Consider whether you need role at all. Native HTML elements like <button>, <nav>, and <table> already carry implicit roles. Use native elements whenever possible instead of adding role attributes to generic <div> or <span> elements.

Valid Roles by Category

Here is a summary of valid, non-abstract ARIA roles you can use:

• Document structure: application, article, blockquote, caption, code, definition, deletion, document, emphasis, feed, figure, generic, group, heading, img, insertion, list, listitem, mark, math, meter, none, note, paragraph, presentation, separator (when not focusable), strong, subscript, superscript, term, time, toolbar, tooltip
• Landmark: banner, complementary, contentinfo, form, main, navigation, region, search
• Live region: alert, log, marquee, status, timer
• Widget: button, checkbox, gridcell, link, menuitem, menuitemcheckbox, menuitemradio, option, progressbar, radio, scrollbar, searchbox, separator (when focusable), slider, spinbutton, switch, tab, tabpanel, textbox, treeitem
• Composite widget: combobox, grid, listbox, menu, menubar, radiogroup, tablist, tree, treegrid
• Table: cell, columnheader, row, rowgroup, rowheader, table
• Window: alertdialog, dialog

Examples

Incorrect: Misspelled Role

A typo in the role value means assistive technologies won’t recognize it.

<div role="nagivation">
  <a href="/">Home</a>
  <a href="/about">About</a>
</div>

Incorrect: Made-Up Role

Using a value that doesn’t exist in the ARIA specification.

<div role="footer-container">
  <p>© 2024 Example Corp</p>
</div>

Incorrect: Abstract Role

Abstract roles are not allowed in markup.

<div role="widget">
  <button>Save</button>
</div>

Correct: Valid ARIA Role

<div role="navigation" aria-label="Main">
  <a href="/">Home</a>
  <a href="/about">About</a>
</div>

Correct: Using Native HTML Instead of a Role

When a native element already carries the semantics you need, prefer it over a role attribute.

<nav aria-label="Main">
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav>

Correct: Valid Widget Role

<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="panel-1">General</button>
  <button role="tab" aria-selected="false" aria-controls="panel-2">Advanced</button>
</div>
<div role="tabpanel" id="panel-1">General settings content</div>
<div role="tabpanel" id="panel-2" hidden>Advanced settings content</div>

Learn more:

Deque Reference

Deque University - How To Fix

→

W3C Reference

W3C WAI ARIA 1.1 - The Roles Model

→