Use aria-roledescription on elements with a semantic role

Rule ID: aria-roledescription
Ruleset: axe-core 4.2
User Impact: Serious
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A)

Start building more accessible experiences

Axe DevTools Pro helps dev teams find and fix up to 80% of accessibility issues while coding. No experience required. Get started with your free trial today.

Compliance Data & Impact

User Impact

Serious
Minor
Critical

Disabilities Affected

  • Blind
  • Deafblind
  • Mobility

Standard(s)

  • WCAG 2.1 (A)
  • WCAG 2.0 (A)

WCAG Success Criteria [WCAG 2.1 (A)]

  • 4.1.2: MUST: Name, Role, Value

WCAG Success Criteria [WCAG 2.0 (A)]

  • 4.1.2: MUST: Name, Role, Value

How to Fix the Problem

ARIA explicitly defines which attributes are allowed for any given role and for every attribute, where that attribute may be used. The detailed information on each attribute can be found by looking at the documentation for each role and/or each attribute.

The aria-roledescription rule includes two failing conditions, three passing conditions, and two incomplete conditions.

aria-roledescription failing conditions:

aria-roledescription returns false for elements with no role value on elements where a role value should be specified.

  • <p aria-roledescription="my paragraph" id="fail1">paragraph</p>
  • <div aria-roledescription="my div" id="fail2">div</div>

aria-roledescription passing conditions:

  • aria-roledescription returns true for elements with an explicitly supported role.
  • aria-roledescription returns true for elements with an implicitly supported role.
  1. <img aria-roledescription="my img" src="foo.png" id="pass1" />
  2. <button aria-roledescription="my button" id="pass2">button</button>
  3. <div role="combobox" aria-roledescription="my combobox" id="pass3"></div>

aria-roledescription incomplete conditions:

aria-roledescription returns undefined for elements with an unsupported role.

  1. <h1 aria-roledescription="my heading" id="incomplete1">heading</h1>
  2. <div role="rowgroup" aria-roledescription="my row" id="incomplete2"></div>

Specific Reference: For more information about which ARIA attributes may or should not be used by HTML element, see ARIA in HTML - Document conformance requirements for use of ARIA attributes in HTML opens in a new window. For more information about using the aria-roledescription attribute, see ARIA in HTML - aria-roledescription (property) opens in a new window.

General Reference: For general ARIA information refer to the following external resources. ARIA is primarily used by web developers and programmers; implementing ARIA effectively usually requires JavaScript skills. Learning ARIA can be a lengthy process due to programming logic complexities and nuances in the specification requiring that ARIA role and aria-roledescription combinations are valid.

Why it Matters

Inappropriate aria-roledescription attribute values that conflict with an element's implied or explicit role value can interfere with the accessibility of the web page. A conflicting aria-roledescription attribute value may result in no effect on the accessibility of the application and may trigger behavior that disables accessibility for entire portions of an application.

When aria-roledescription> attributes are applied to HTML elements not in accordance with WAI-ARIA 1.1, semantics conflict between the aria-roledescription value and the implicit or explicit element role value which may result in assistive technology products reporting nonsensical user interface (UI) information that does not correctly represent the intended UI experience.

Rule Description

Ensures that the aria-roledescription attribute is only used on elements with an implicit or explicit role values.

The Algorithm (in simple terms)

Use aria-roledescription values to appropriately describe implied or explicit element role values.

Resources

Was this information helpful?

You have already given your feedback, thank you..

Your response was as follows:

Was this information helpful?
Date/Time feedback was submitted: