« 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 aria-roledescription but no role at all, explicit or implicit. This is a misuse of the attribute, aria-roledescription is intended to relabel an existing role, not create one from nothing.

Expected result: worth confirming directly, spec guidance advises against this pattern, but what different screen readers actually do with a roledescription on a roleless element (ignore it, announce it anyway, or something else) is worth testing rather than assuming.

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

Example 5: 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 misuse case in Example 4 specifically, has not been verified here.

« Back to home