ARIA attributes must use valid names and values for WCAG

ARIA attributes that begin with aria- must use valid, recognized names

Only ARIA attributes defined by the WAI-ARIA specification are allowed. Misspelled or non-existent aria-* attributes are ignored by browsers and assistive technology. This breaks announcements, states, and relationships relied on by screen reader users.

Why It Matters

Invalid ARIA does nothing at best and misleads users at worst. Screen readers cannot expose states like expanded, checked, or hidden if the attribute name or value is wrong. Users who depend on assistive tech may miss feedback about changes or control states, leading to confusion and errors.

Incorrect ARIA can also create traps for keyboard users when custom widgets rely on ARIA for state but the mappings fail. Consistent, valid ARIA helps everyone by providing predictable behavior across AT and browsers.

Common Causes

• Typos in attribute names (e.g., aria-lable, aria-expaned).
• Using attributes that do not exist (e.g., aria-visible, aria-pressedlabel).
• Invalid values or case (e.g., aria-hidden="Maybe" or aria-expanded="yes").
• Applying states/properties to roles that do not support them (e.g., aria-checked on a generic link with no checkbox role).
• Copy-paste from outdated snippets or libraries with custom aria-* names.
• Mixing up data-* attributes with ARIA (using aria-* for custom data instead of data-*).

How to Fix

1. Inventory all aria-* attributes
   • Search the codebase for "aria-" in templates, components, and scripts.
2. Verify the attribute name
   • Cross-check each attribute against the WAI-ARIA States and Properties index (current ARIA spec). Names are lowercase with hyphens and must match exactly.
3. Verify the value type
   • Use only allowed tokens/values for each attribute:
   • true/false/mixed (boolean/tri-state) where specified
   • Token strings like none, listbox, both, assertive, polite
   • Numbers (e.g., aria-valuenow) or ranges (aria-valuemin/max)
   • ID reference(s) for attributes that expect element IDs (e.g., aria-labelledby, aria-controls)
   • Values are case-sensitive and typically lowercase.
4. Check role support
   • Ensure the attribute is permitted for the element’s implicit role or its explicit role (role="..."). If not supported, remove the attribute or use a role that supports that state/property.
5. Replace non-ARIA needs
   • Do not invent aria-* names for custom data. Use data-* attributes instead.
6. Validate automatically
   • Run a validator (W3C Nu HTML Checker), accessibility linters (axe, axe-core in tests), and static analysis (eslint-plugin-jsx-a11y or aria-query for React) in CI.
7. Retest interactions
   • When ARIA affects interactive UI, confirm announcements and state changes with a screen reader after fixes.

How to Test

Keyboard check

• Operate all interactive controls with the keyboard.
• Confirm visual states change appropriately when toggled (e.g., menus open/close) so you know which ARIA states should be updated.

Screen reader check

• With NVDA/JAWS/VoiceOver, navigate to controls that use ARIA.
• Confirm states are announced correctly (e.g., expanded/collapsed, checked/unchecked, busy, invalid).
• Verify labels and relationships (e.g., aria-labelledby, aria-controls) reference existing elements.

Automated/DevTools check

• Run W3C Nu HTML Checker and an automated a11y scanner (axe, Lighthouse).
• In browser DevTools Accessibility pane, inspect the element’s computed ARIA name, role, and properties. Ensure the expected states/properties appear and values are valid.

Checklist

• No misspelled or undefined aria-* attributes.
• Attribute values match allowed tokens/types for that attribute.
• Attributes are used only on roles that support them.
• IDREF/IDREFS values point to existing element IDs.
• Automated tools show no invalid ARIA attribute errors.
• Screen reader announces correct names, roles, and states.

Good Example

<button id="menuToggle" aria-expanded="false" aria-controls="siteMenu">Menu</button>
<nav id="siteMenu" hidden>
  <ul role="menu">
    <li role="menuitem"><a href="/products">Products</a></li>
    <li role="menuitem"><a href="/pricing">Pricing</a></li>
  </ul>
</nav>
<script>
  const btn = document.getElementById('menuToggle');
  const menu = document.getElementById('siteMenu');
  btn.addEventListener('click', () => {
    const isOpen = btn.getAttribute('aria-expanded') === 'true';
    btn.setAttribute('aria-expanded', String(!isOpen));
    if (isOpen) {
      menu.setAttribute('hidden', '');
    } else {
      menu.removeAttribute('hidden');
    }
  });
</script>

Why this is good

• Recognized attributes: aria-expanded, aria-controls.
• Valid boolean token values: true/false.
• IDs match and reference existing element.

Bad Example

<button aria-expaned="yes" aria-control="mainNav" aria-visible="true">Menu</button>
<nav id="mainNav" style="display:none">
  <!-- ... -->
</nav>

What’s wrong

• Misspelled names: aria-expaned, aria-control.
• Non-existent attribute: aria-visible.
• Invalid values: "yes" is not allowed for aria-expanded.
• The relationship fails because aria-control doesn’t map to any ARIA feature.

Quick Checklist

• Use only ARIA names defined in the current WAI-ARIA spec.
• Keep names lowercase and spelled exactly (with correct hyphens).
• Provide only allowed values (true/false/mixed, valid tokens, numbers, or IDREF/IDREFS as required).
• Ensure the attribute is supported by the element’s role.
• Reference existing element IDs for labeling/controls.
• Prefer data-* for custom data (do not invent aria-* attributes).
• Validate with automated tools and confirm behavior with a screen reader.