Valid ARIA role values are required

Elements with role require valid ARIA role values only

All role="" attributes must use real ARIA roles, spelled correctly, and not abstract roles.

This issue appears in custom components, JavaScript widgets, and templates that inject ARIA.

People using screen readers or other assistive tech rely on correct roles to navigate and operate controls.

Why It Matters

Incorrect or unknown roles are ignored by assistive technologies, so users may not learn what an element is or how to interact with it.

Typos or made-up roles break navigation landmarks, control identification, and announcements of dynamic updates.

This directly impacts users who rely on screen readers, speech input, or alternative navigation, and can also confuse browser accessibility trees.

Common Causes

• Misspelled roles (e.g., role="buton", "navigtion").
• Invented roles (e.g., role="navigation-bar", "modal-window").
• Using abstract roles (e.g., role="widget", "landmark", "command").
• Overriding native semantics unnecessarily (e.g., role="button" on <a> without button behavior).
• role="presentation" or role="none" on focusable/interactive elements.
• Frameworks or CMS snippets injecting placeholder or legacy roles.

How to Fix

1. Prefer native HTML first:
   • Use semantic elements (<button>, <nav>, <main>, <table>, <ul>, <img>) instead of adding ARIA roles.
   • Only add a role when native markup cannot express the needed semantics.
2. Use only valid, concrete roles:
   • Landmark examples: banner, navigation, main, search, complementary, contentinfo, region (with aria-label or aria-labelledby).
   • Widget examples: button, link, checkbox, radio, switch, slider, tab, tablist, tabpanel, combobox, listbox, option, grid, gridcell, menu, menuitem, dialog, alertdialog, progressbar, textbox, searchbox.
   • Structural/content examples: article, heading, list, listitem, table, row, cell, img, figure, code, time, math.
   • Separator nuance: focusable separators are widgets (role="separator"); non-focusable separators are structural.
3. Never use abstract roles:
   • Do not use roles like roletype, widget, composite, command, input, range, section, sectionhead, select, structure, landmark, window.
4. Keep spelling exact and case-insensitive:
   • role values are case-insensitive, but spelling must match the ARIA spec.
5. Avoid breaking implicit roles:
   • Don’t override useful native roles unless the behavior fully matches the new role (keyboard, states, and properties).
   • Do not use role="presentation"/"none" on focusable or interactive elements.
6. For composite widgets, meet required structure:
   • Example: tablist must contain tab elements, each tab controls a tabpanel; a grid contains rows and gridcells.
7. Validate and lint:
   • Run automated accessibility checks and inspect the browser’s Accessibility tree to confirm the computed role.

How to Test

• Keyboard check:
• Navigate the page using Tab/Shift+Tab and arrow keys for widgets.
• Verify controls behave as their roles imply (e.g., Space/Enter for buttons, arrow keys for tabs/menus/sliders).
• Screen reader check:
• NVDA + Firefox or JAWS + Chromium: confirm each element is announced with the expected role (e.g., "button", "navigation landmark", "dialog").
• VoiceOver on macOS/iOS: use the rotor to list Landmarks and verify correct entries (Main, Navigation, Search, etc.).
• Visual/DevTools check:
• Inspect elements and view the Accessibility tree. Ensure the computed role matches the intended role.
• Check for typos, invented roles, or abstract roles.
• Automation:
• Run an accessibility linter or audit to flag invalid role values and conflicts with implicit roles.

Good Example

<div class="modal" role="dialog" aria-modal="true" aria-labelledby="subscribe-title">
  <h2 id="subscribe-title">Subscribe to updates</h2>
  <form>
    <label for="email">Email</label>
    <input id="email" type="email">
    <button type="submit">Sign up</button>
  </form>
</div>

<nav aria-label="Primary">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/pricing">Pricing</a></li>
  </ul>
</nav>

<div role="status" aria-live="polite" id="save-msg" hidden>Saved.</div>

Why this is good:

• Uses concrete roles (dialog, status) and native elements where possible.
• Landmarks are valid and discoverable.
• No abstract or invented role values.

Bad Example

<div role="modal-window" aria-modal="true"> ... </div>
<nav role="navigation-bar"> ... </nav>
<a href="#" role="button" tabindex="0">Open</a>
<hr role="separator" tabindex="0">
<section role="landmark"> ... </section>
<button role="none">Submit</button>

What’s wrong:

• modal-window and navigation-bar are not valid ARIA roles.
• role="landmark" is abstract and must not be used.
• role="none" removes semantics from a focusable control (button), which is not allowed.
• Focusable <hr> as role="separator" implies a widget; without widget behavior, it’s misleading.
• <a> pretending to be a button lacks full button behavior unless fully implemented (prefer <button>).

Quick Checklist

• role="" uses only valid, concrete ARIA roles from the spec.
• No abstract roles (e.g., widget, landmark, command) anywhere.
• Spelling is exact; no invented or legacy role names.
• Prefer native HTML semantics; add ARIA roles only when needed.
• Do not remove semantics from focusable or interactive elements with role="none"/"presentation".
• Composite widgets meet required child roles and keyboard patterns.
• Computed roles in the Accessibility tree match expectations.
• Screen readers announce landmarks and widgets as intended.