aria-describedby

When to use

For supplementary information that sits next to a control: a format hint under a date field (“MM/DD/YYYY”), a password-strength rule list, an inline error message, the instructions above a complex widget. The label answers what is this?; the description answers anything else I need to know?.

Use it on form inputs, buttons, dialogs, and any custom widget where extra context belongs after the name.

How it behaves

The value is a space-separated list of element IDs, same shape as aria-labelledby. Screen readers announce the description after the accessible name and role, usually after a short pause — “Email, edit, We will only contact you about this order.” Multiple IDs concatenate in the order they are listed.

The description is not the name. It does not appear in the accessibility tree’s name field, so axe-core will not count it as labelling the control. If the control has no name, aria-describedby cannot rescue it.

If the description changes (e.g. an error appears), update the referenced element’s text content rather than swapping the aria-describedby value — many AT do not re-announce when the attribute itself changes, but they do re-announce when the referenced text is part of a live region or when focus enters the field again.

Common failures

• Using aria-describedby for what should be the name. The control still has no label; the user hears the description but never the name.
• Pointing at an ID that does not exist or that has been removed from the DOM by a render.
• Adding aria-describedby to a non-focusable element. Most browsers expose the description only when the element gets focus or is queried directly.
• Long marketing copy as a description — verbose announcements push users to disable descriptions globally.
• Forgetting to associate inline form errors. aria-describedby="email-error" plus aria-invalid="true" is the canonical pattern; without the reference the error is visible but silent.
• Reusing the same description ID for many fields with aria-describedby="hint" — works, but check that the same text actually applies to every field.

Example

<label for="password">Password</label>
<input
  id="password"
  type="password"
  aria-describedby="pw-rules pw-error"
  aria-invalid="true"
>
<p id="pw-rules">At least 12 characters, including a number.</p>
<p id="pw-error">Password is too short.</p>