« Back to home

Testing aria-roledescription

aria-roledescription defines a human-readable, author-supplied description that replaces the announced role of an element, without changing the element's actual role, behaviour, or keyboard support. It is typically used to give a more specific or meaningful name to a generic or repeated pattern, for example, announcing "slide" instead of "group" for one panel in a carousel.

Example 1: without aria-roledescription

This element has role="group" and no aria-roledescription, so its role should be announced normally.

Expected result: the role should be announced as "group".

<div role="group" aria-label="Photo of a mountain lake at sunrise">
  Slide 1 of 3
</div>

Example 2: with aria-roledescription

This element has the same underlying role="group", but adds aria-roledescription. The element's actual role, and how assistive technology interacts with it, does not change, only the word announced for its type should change.

Expected result: the role should be announced as "slide" instead of "group", while the element continues to behave as a group in every other respect.

<div
  role="group"
  aria-roledescription="slide"
  aria-label="Photo of a mountain lake at sunrise"
>
  Slide 1 of 3
</div>

Example 3: real-world use, filling a gap in the role vocabulary

ARIA defines role="radiogroup" as a real, dedicated role for grouping radio buttons. There is no equivalent role for checkboxes, a <fieldset> containing checkboxes only ever exposes the generic group role, regardless of what it contains. aria-roledescription can fill that gap by supplying a more specific, meaningful label where ARIA itself doesn't provide one.

Expected result: without aria-roledescription, this fieldset would be announced only as "group". With it, the role should be announced as "checkboxgroup" instead, giving screen reader users more specific context than ARIA's role vocabulary alone can provide, without changing how the individual checkboxes behave or are navigated.

<fieldset aria-roledescription="checkboxgroup">
  <legend>Newsletter interests</legend>
  <ul>
    <li>
      <input type="checkbox" id="interests-bats" name="subscribe">
      <label for="interests-bats">Bats</label>
    </li>
    <!-- remaining checkboxes follow the same pattern -->
  </ul>
</fieldset>

Example 4: misuse, no underlying role

This element has no explicit role attribute. But per ARIA 1.2, a plain <div> isn't actually roleless, its implicit role is generic, and generic is specifically one of the roles where naming is prohibited. Per the HTML Accessibility API Mappings spec, user agents must not expose aria-roledescription on an element with no corresponding role, or mapped to the generic role, unless the element also has an explicit, conforming role that doesn't itself prohibit the attribute. This isn't "no role, so nothing to relabel", it's a specific role that disallows this specific attribute.

Expected result: per spec, this aria-roledescription should be stripped and not exposed to assistive technology at all, since it isn't permitted on the generic role this element implicitly has. Confirm directly what your standard AT/browser combinations actually do, implementation of this specific prohibition has historically been inconsistent.

<div aria-roledescription="slide">
  Slide 1 of 3
</div>
<!-- implicit role: generic -->

Example 5: misuse, explicit prohibited role

generic is a real, valid ARIA role, not just a placeholder for "no role", it's the exact role Example 4's roleless <div> implicitly has. Stating it explicitly doesn't grant permission to add aria-roledescription, the prohibition applies to the role itself, however it got there.

Expected result: the same outcome as Example 4, per spec this aria-roledescription should be stripped and not exposed to assistive technology, since generic explicitly prohibits it. Confirm directly what your standard AT/browser combinations actually do.

<div role="generic" aria-roledescription="slide">
  Slide 1 of 3
</div>

Example 6: empty value

An empty aria-roledescription attribute provides no meaningful description and will be flagged as an authoring issue.

Expected result: the element has a valid underlying role but the roledescription value is empty, so no custom role name will be announced. The role will fall back to the underlying "group".

<div
  role="group"
  aria-roledescription=""
  aria-label="Photo of a mountain lake at sunrise"
>
  Slide 1 of 3
</div>

Note for testing: confirm all results above with your standard browser and screen reader combinations before treating them as settled. aria-roledescription support, and behaviour for the two misuse cases in Examples 4 and 5 specifically, has not been verified here.

« Back to home