• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar
Digital A11Y

Digital A11Y

Your Accessibility Partner

  • About
  • Articles
  • WAI-ARIA
  • WCAG
  • Resources
    • Cheat Sheets
    • A11Y Blogs
    • A11Y Toolkit
  • Contact

aria-roledescription(properties)

Defines a human-readable, author-localized description for the role of an element.

Description

New in ARIA 1.1

Defines a human-readable, author-localized description for the role of an element.

Some assistive technologies, such as screen readers, present the role of an element as part of the user experience. Such assistive technologies typically localize the name of the role, and they may customize it as well. Users of these assistive technologies depend on the presentation of the role name, such as “region,” “button,” or “slider,” for an understanding of the purpose of the element and, if it is a widget, how to interact with it.

The aria-roledescription property gives authors the ability to override how assistive technologies localize and express the name of a role. Thus inappropriately using aria-roledescription may inhibit users’ ability to understand or interact with an element. Authors SHOULD limit use of aria-roledescription to clarifying the purpose of non-interactive container roles like group or region, or to providing a more specific description of a widget.

When using aria-roledescription, authors SHOULD also ensure that:

The element to which aria-roledescription is applied has a valid WAI-ARIA role or has an implicit WAI-ARIA role semantic.

The value of aria-roledescription is not empty or does not contain only whitespace characters.

User agents MUST NOT expose the aria-roledescription property if any of the following conditions exist:

The element to which aria-roledescription is applied does not have a valid WAI-ARIA role or does not have an implicit WAI-ARIA role semantic.

The value of aria-roledescription is empty or contains only whitespace characters.

Assistive technologies SHOULD use the value of aria-roledescription when presenting the role of an element, but SHOULD NOT change other functionality based on the role of an element that has a value for aria-roledescription. For example, an assistive technology that provides functions for navigating to the next region or button SHOULD allow those functions to navigate to regions and buttons that have an aria-roledescription.

Example

HTML Example

The following two examples show the use of aria-roledescription to indicate that a non-interactive container is a “slide” in a web-based presentation application.

<div role="region" aria-roledescription="slide" id="slide42" aria-labelledby="slide42heading">
<h1 id="slide42heading">Quarterly Report</h1>
<!-- remaining slide contents -->
</div>

<section aria-roledescription="slide" id="slide42" aria-labelledby="slide42heading">
<h1 id="slide42heading">Quarterly Report</h1>
<!-- remaining slide contents -->
</section>
A screen reader user may hear “Quarterly Report, slide” rather than the more vague “Quarterly Report, region” or “Quarterly Report, group.”

HTML Example 2

The following examples show the use of aria-roledescription to indicate that a button in a web-based email client is associated with an “attachment.”

<div role="button" tabindex="0" aria-roledescription="attachment button">family_reunion.jpg</div>
<button aria-roledescription="attachment button">family_reunion.jpg</button>
Because “button” is part of the localized description, a screen reader user should still understand how to interact with that control.

Characteristics

Used in Roles

  • All elements of the base markup

Value

  • string
    • Unconstrained value type.

Semantic HTML

No HTML element equivalent.

The aria-roledescription attribute is meant to suppress the native role of an element and replace it with whatever the attribute string value states.

It’s important to note that the underlying role mapping remains the same in the browser and accessibility API, however assistive technologies like screen readers will announce only the value of aria-roledescription as the role of the element instead of the actual role that is mapped. At least, this is what the specification states.

However, some screen reader venders have already stated that they will not prevent the role from being conveyed to their users because this would cause too much confusion, but will instead announce both, thus forecasting that they have no intention to follow the spec in this matter. This will result in some screen reader vendors suppressing the role and others not, making this an unreliable attribute at best, and potentially an extremely dangerous feature if misused by conveying the wrong role or an incomprehensible role on critical interactive controls.

Reference

W3C (opens new window)

Share A11Y Love

  • Twitter
  • LinkedIn
  • Facebook
  • Reddit

Primary Sidebar

Get Digital A11Y in Your Inbox

Recent A11Y Articles

  • Understanding SC 4.1.3 Status messages
  • Understanding SC 2.5.4 Motion Actuation
  • Understanding SC 2.5.3 Label in Name
  • Knowbility looking for mentors in its Accessible Internet Rally
  • Understanding SC 2.5.2 Pointer Cancellation

Recent Comments

  • Al on Understanding SC 4.1.2 Name, Role, Value
  • Randy on Screen Readers & Browsers! Which is the Best Combination for Accessibility Testing?
  • Raghavendra Satish Peri on Screen Readers & Browsers! Which is the Best Combination for Accessibility Testing?
  • Raghavendra Satish Peri on Understanding SC 1.4.12 Text Spacing
  • Raghavendra Satish Peri on Understanding SC 4.1.2 Name, Role, Value

A11Y Categories

  • Design
  • Events
  • HTML
  • IOS
  • Mobile Accessibility
  • News
  • Tools
  • Uncategorized
  • WAI-ARIA
  • WCAG
  • Web Accessibility

  • Privacy Policy
  • Sitemap
© 2021 Digital A11Y