Search code examples
htmlaccessibilitywai-aria

Using aria-describedby to reference description that contains more than just text

Let's say I have the following markup:

<label for="input">Description<label>
<textarea id="input" aria-describedby="help"></textarea>
<div id="help">
  <kbd>Enter<kbd> to create a new line
</div>

The aria-describedby tag references the help text which contains a <kbd> element as well. Is this valid? I read the following on MDN:

Note: The aria-describedby content should only be a text string. If there are important underlying semantics in the content, consider using aria-details.

Solution

  • From the aria-describedby entry on MDN Web Docs:

    The aria-describedby property is appropriate when the associated content contains descriptions experienced as plain text. If the content contains a large amount of content, useful semantics, or has a complex structure requiring user navigation, use aria-details.

    The <kbd> element qualifies as "useful semantics". Without it, a screen reader user would just hear—

    Enter to create a new line

    —which they might interpret as instructing them to move focus into (e.g. "enter" into) a new area in order to create a new line.

    Therefore you should use aria-details instead of aria-describedby.

    Additionally, since all screen readers are different and some might not announce the semantics of the <kbd> element, it would be more robust to reword the text to be—

    Press <kbd>enter<kbd> to create a new line.

    —so that it's clearer that "Enter" is a key, even without the semantics provided by <kbd>.